Commit 173b18c7 authored by Nick Mathewson's avatar Nick Mathewson 🏃
Browse files

Add about 60 more DOCDOC comments to 0.2.3

Also, try to resolve some doxygen issues.  First, define a magic
"This is doxygen!" macro so that we take the correct branch in
various #if/#else/#endifs in order to get the right documentation.
Second, add in a few grouping @{ and @} entries in order to get some
variables and fields to get grouped together.
parent b353cd7e
......@@ -156,7 +156,7 @@ tor_fopen_cloexec(const char *path, const char *mode)
return result;
}
#ifdef HAVE_SYS_MMAN_H
#if defined(HAVE_SYS_MMAN_H) || defined(RUNNING_DOXYGEN)
/** Try to create a memory mapping for <b>filename</b> and return it. On
* failure, return NULL. Sets errno properly, using ERANGE to mean
* "empty file". */
......@@ -501,10 +501,13 @@ tor_memmem(const void *_haystack, size_t hlen,
#endif
}
/* Tables to implement ctypes-replacement TOR_IS*() functions. Each table
/**
* Tables to implement ctypes-replacement TOR_IS*() functions. Each table
* has 256 bits to look up whether a character is in some set or not. This
* fails on non-ASCII platforms, but it is hard to find a platform whose
* character set is not a superset of ASCII nowadays. */
/**@{*/
const uint32_t TOR_ISALPHA_TABLE[8] =
{ 0, 0, 0x7fffffe, 0x7fffffe, 0, 0, 0, 0 };
const uint32_t TOR_ISALNUM_TABLE[8] =
......@@ -517,8 +520,10 @@ const uint32_t TOR_ISPRINT_TABLE[8] =
{ 0, 0xffffffff, 0xffffffff, 0x7fffffff, 0, 0, 0, 0x0 };
const uint32_t TOR_ISUPPER_TABLE[8] = { 0, 0, 0x7fffffe, 0, 0, 0, 0, 0 };
const uint32_t TOR_ISLOWER_TABLE[8] = { 0, 0, 0, 0x7fffffe, 0, 0, 0, 0 };
/* Upper-casing and lowercasing tables to map characters to upper/lowercase
* equivalents. */
/** Upper-casing and lowercasing tables to map characters to upper/lowercase
* equivalents. Used by tor_toupper() and tor_tolower(). */
/**@{*/
const char TOR_TOUPPER_TABLE[256] = {
0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,
16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,
......@@ -555,6 +560,7 @@ const char TOR_TOLOWER_TABLE[256] = {
224,225,226,227,228,229,230,231,232,233,234,235,236,237,238,239,
240,241,242,243,244,245,246,247,248,249,250,251,252,253,254,255,
};
/**@}*/
/** Helper for tor_strtok_r_impl: Advances cp past all characters in
* <b>sep</b>, and returns its new value. */
......@@ -1779,9 +1785,11 @@ make_path_absolute(char *fname)
#ifndef HAVE__NSGETENVIRON
#ifndef HAVE_EXTERN_ENVIRON_DECLARED
/* Some platforms declare environ under some circumstances, others don't. */
#ifndef RUNNING_DOXYGEN
extern char **environ;
#endif
#endif
#endif
/** Return the current environment. This is a portable replacement for
* 'environ'. */
......@@ -2356,6 +2364,7 @@ tor_gettimeofday(struct timeval *timeval)
#define TIME_FNS_NEED_LOCKS
#endif
/* DOCDOC correct_tm */
static struct tm *
correct_tm(int islocal, const time_t *timep, struct tm *resultbuf,
struct tm *r)
......
......@@ -6,9 +6,8 @@
* \brief Wrappers to handle porting between different versions of libevent.
*
* In an ideal world, we'd just use Libevent 2.0 from now on. But as of June
* 2009, Libevent 2.0 is still in alpha, and we will have old versions of
* Libevent for the forseeable future.
**/
* 2012, Libevent 1.4 is still all over, and some poor souls are stuck on
* Libevent 1.3e. */
#include "orconfig.h"
#include "compat.h"
......@@ -57,7 +56,7 @@ typedef uint32_t le_version_t;
static le_version_t tor_get_libevent_version(const char **v_out);
#ifdef HAVE_EVENT_SET_LOG_CALLBACK
#if defined(HAVE_EVENT_SET_LOG_CALLBACK) || defined(RUNNING_DOXYGEN)
/** A string which, if it appears in a libevent log, should be ignored. */
static const char *suppress_msg = NULL;
/** Callback function passed to event_set_log() so we can intercept
......
......@@ -59,6 +59,7 @@ struct timeval;
int tor_event_base_loopexit(struct event_base *base, struct timeval *tv);
#endif
/* DOCDOC tor_libevent_cfg */
typedef struct tor_libevent_cfg {
int disable_iocp;
int num_cpus;
......
......@@ -69,7 +69,7 @@
/** Longest recognized */
#define MAX_DNS_LABEL_SIZE 63
#if OPENSSL_VERSION_NUMBER < OPENSSL_V_SERIES(0,9,8)
#if OPENSSL_VERSION_NUMBER < OPENSSL_V_SERIES(0,9,8) && !defined(RUNNING_DOXYGEN)
/** @{ */
/** On OpenSSL versions before 0.9.8, there is no working SHA256
* implementation, so we use Tom St Denis's nice speedy one, slightly adapted
......@@ -404,6 +404,8 @@ crypto_cipher_new_with_iv(const char *key, const char *iv)
return env;
}
/** Return a new crypto_cipher_t with the provided <b>key</b> and an IV of all
* zero bytes. */
crypto_cipher_t *
crypto_cipher_new(const char *key)
{
......
......@@ -97,6 +97,7 @@ should_log_function_name(log_domain_mask_t domain, int severity)
/** A mutex to guard changes to logfiles and logging. */
static tor_mutex_t log_mutex;
/* DOCDOC log_mutex_initialized */
static int log_mutex_initialized = 0;
/** Linked list of logfile_t. */
......
......@@ -41,6 +41,7 @@ static void tor_process_monitor_poll_cb(evutil_socket_t unused1, short unused2,
/* This struct may contain pointers into the original process
* specifier string, but it should *never* contain anything which
* needs to be freed. */
/* DOCDOC parsed_process_specifier_t */
struct parsed_process_specifier_t {
pid_t pid;
};
......@@ -81,6 +82,7 @@ parse_process_specifier(const char *process_spec,
return -1;
}
/* DOCDOC tor_process_monitor_t */
struct tor_process_monitor_t {
/** Log domain for warning messages. */
log_domain_mask_t log_domain;
......@@ -152,6 +154,7 @@ tor_validate_process_specifier(const char *process_spec,
#define PERIODIC_TIMER_FLAGS (0)
#endif
/* DOCDOC poll_interval_tv */
static struct timeval poll_interval_tv = {15, 0};
/* Note: If you port this file to plain Libevent 2, you can make
* poll_interval_tv const. It has to be non-const here because in
......
......@@ -14,6 +14,7 @@
typedef struct tor_process_monitor_t tor_process_monitor_t;
/* DOCDOC tor_procmon_callback_t */
typedef void (*tor_procmon_callback_t)(void *);
int tor_validate_process_specifier(const char *process_spec,
......
......@@ -153,7 +153,7 @@ void tor_log(int severity, log_domain_mask_t domain, const char *format, ...)
CHECK_PRINTF(3,4);
#define log tor_log /* hack it so we don't conflict with log() as much */
#ifdef __GNUC__
#if defined(__GNUC__) || defined(RUNNING_DOXYGEN)
extern int _log_global_min_severity;
void _log_fn(int severity, log_domain_mask_t domain,
......
......@@ -225,6 +225,7 @@ static int check_cert_lifetime_internal(int severity, const X509 *cert,
/** Global TLS contexts. We keep them here because nobody else needs
* to touch them. */
static tor_tls_context_t *server_tls_context = NULL;
/* DOCDOC client_tls_context */
static tor_tls_context_t *client_tls_context = NULL;
/** True iff tor_tls_init() has been called. */
......@@ -268,6 +269,7 @@ tor_tls_get_state_description(tor_tls_t *tls, char *buf, size_t sz)
tor_snprintf(buf, sz, "%s%s", ssl_state, tortls_state);
}
/* DOCDOC tor_tls_log_one_error */
void
tor_tls_log_one_error(tor_tls_t *tls, unsigned long err,
int severity, int domain, const char *doing)
......@@ -1342,6 +1344,7 @@ tor_tls_client_is_using_v2_ciphers(const SSL *ssl, const char *address)
return 1;
}
/* DOCDOC tor_tls_debug_state_callback */
static void
tor_tls_debug_state_callback(const SSL *ssl, int type, int val)
{
......@@ -1621,6 +1624,7 @@ tor_tls_block_renegotiation(tor_tls_t *tls)
tls->ssl->s3->flags &= ~SSL3_FLAGS_ALLOW_UNSAFE_LEGACY_RENEGOTIATION;
}
/* DOCDOC tor_tls_assert_renegotiation_unblocked */
void
tor_tls_assert_renegotiation_unblocked(tor_tls_t *tls)
{
......
......@@ -3303,6 +3303,7 @@ tor_process_get_stdout_pipe(process_handle_t *process_handle)
return process_handle->stdout_pipe;
}
#else
/* DOCDOC tor_process_get_stdout_pipe */
FILE *
tor_process_get_stdout_pipe(process_handle_t *process_handle)
{
......@@ -3310,6 +3311,7 @@ tor_process_get_stdout_pipe(process_handle_t *process_handle)
}
#endif
/* DOCDOC process_handle_new */
static process_handle_t *
process_handle_new(void)
{
......@@ -4289,6 +4291,7 @@ get_string_from_pipe(FILE *stream, char *buf_out, size_t count)
return IO_STREAM_TERM;
}
/* DOCDOC tor_check_port_forwarding */
void
tor_check_port_forwarding(const char *filename, int dir_port, int or_port,
time_t now)
......
......@@ -72,6 +72,7 @@
/* Memory management */
void *_tor_malloc(size_t size DMALLOC_PARAMS) ATTR_MALLOC;
void *_tor_malloc_zero(size_t size DMALLOC_PARAMS) ATTR_MALLOC;
/* DOCDOC _tor_malloc_roundup */
void *_tor_malloc_roundup(size_t *size DMALLOC_PARAMS) ATTR_MALLOC;
void *_tor_calloc(size_t nmemb, size_t size DMALLOC_PARAMS) ATTR_MALLOC;
void *_tor_realloc(void *ptr, size_t size DMALLOC_PARAMS);
......@@ -382,6 +383,7 @@ HANDLE load_windows_system_library(const TCHAR *library_name);
int environment_variable_names_equal(const char *s1, const char *s2);
/* DOCDOC process_environment_t */
struct process_environment_t {
/** A pointer to a sorted empty-string-terminated sequence of
* NUL-terminated strings of the form "NAME=VALUE". */
......
#include "util.h"
/** DOCDOC */
const char *
libor_get_digests(void)
{
......
......@@ -108,7 +108,7 @@ chunk_repack(chunk_t *chunk)
chunk->data = &chunk->mem[0];
}
#ifdef ENABLE_BUF_FREELISTS
#if defined(ENABLE_BUF_FREELISTS) || defined(RUNNING_DOXYGEN)
/** A freelist of chunks. */
typedef struct chunk_freelist_t {
size_t alloc_size; /**< What size chunks does this freelist hold? */
......
......@@ -236,6 +236,7 @@ circuit_build_times_quantile_cutoff(void)
return num/100.0;
}
/* DOCDOC circuit_build_times_get_bw_scale */
int
circuit_build_times_get_bw_scale(networkstatus_t *ns)
{
......@@ -4972,6 +4973,7 @@ find_bridge_by_digest(const char *digest)
return NULL;
}
/* DOCDOC find_transport_name_by_bridge_addrport */
const char *
find_transport_name_by_bridge_addrport(const tor_addr_t *addr, uint16_t port)
{
......
......@@ -147,6 +147,7 @@ void circuit_build_times_network_is_live(circuit_build_times_t *cbt);
int circuit_build_times_network_check_live(circuit_build_times_t *cbt);
void circuit_build_times_network_circ_success(circuit_build_times_t *cbt);
/* DOCDOC circuit_build_times_get_bw_scale */
int circuit_build_times_get_bw_scale(networkstatus_t *ns);
void clear_transport_list(void);
......@@ -157,6 +158,7 @@ void transport_free(transport_t *transport);
transport_t *transport_new(const tor_addr_t *addr, uint16_t port,
const char *name, int socks_ver);
/* DOCDOC find_transport_name_by_bridge_addrport */
const char *find_transport_name_by_bridge_addrport(const tor_addr_t *addr,
uint16_t port);
......
......@@ -786,6 +786,7 @@ extern const char tor_git_revision[]; /* from tor_main.c */
/** The version of this Tor process, as parsed. */
static char *the_tor_version = NULL;
/* DOCDOC the_short_tor_version */
static char *the_short_tor_version = NULL;
/** Return the current Tor version. */
......
const char *tor_get_digests(void);
/** DOCDOC */
const char *
tor_get_digests(void)
{
......
......@@ -80,6 +80,7 @@ static int get_proxy_type(void);
* XXX024 We should really use the entire list of interfaces here.
**/
static tor_addr_t *last_interface_ipv4 = NULL;
/* DOCDOC last_interface_ipv6 */
static tor_addr_t *last_interface_ipv6 = NULL;
/** A list of tor_addr_t for addresses we've used in outgoing connections.
* Used to detect IP address changes. */
......@@ -731,7 +732,7 @@ connection_expire_held_open(void)
});
}
#ifdef HAVE_SYS_UN_H
#if defined(HAVE_SYS_UN_H) || defined(RUNNING_DOXYGEN)
/** Create an AF_UNIX listenaddr struct.
* <b>listenaddress</b> provides the path to the Unix socket.
*
......@@ -2730,6 +2731,7 @@ connection_handle_read_impl(connection_t *conn)
return 0;
}
/* DOCDOC connection_handle_read */
int
connection_handle_read(connection_t *conn)
{
......@@ -3322,6 +3324,7 @@ connection_handle_write_impl(connection_t *conn, int force)
return 0;
}
/* DOCDOC connection_handle_write */
int
connection_handle_write(connection_t *conn, int force)
{
......
......@@ -92,8 +92,10 @@ int connection_flush(connection_t *conn);
void _connection_write_to_buf_impl(const char *string, size_t len,
connection_t *conn, int zlib);
/* DOCDOC connection_write_to_buf */
static void connection_write_to_buf(const char *string, size_t len,
connection_t *conn);
/* DOCDOC connection_write_to_buf_zlib */
static void connection_write_to_buf_zlib(const char *string, size_t len,
dir_connection_t *conn, int done);
static INLINE void
......@@ -108,7 +110,9 @@ connection_write_to_buf_zlib(const char *string, size_t len,
_connection_write_to_buf_impl(string, len, TO_CONN(conn), done ? -1 : 1);
}
/* DOCDOC connection_get_inbuf_len */
static size_t connection_get_inbuf_len(connection_t *conn);
/* DOCDOC connection_get_outbuf_len */
static size_t connection_get_outbuf_len(connection_t *conn);
static INLINE size_t
......
......@@ -457,7 +457,7 @@ connection_edge_about_to_close(edge_connection_t *edge_conn)
}
}
/* Called when we're about to finally unlink and free an AP (client)
/** Called when we're about to finally unlink and free an AP (client)
* connection: perform necessary accounting and cleanup */
void
connection_ap_about_to_close(entry_connection_t *entry_conn)
......@@ -492,7 +492,7 @@ connection_ap_about_to_close(entry_connection_t *entry_conn)
circuit_detach_stream(circ, edge_conn);
}
/* Called when we're about to finally unlink and free an exit
/** Called when we're about to finally unlink and free an exit
* connection: perform necessary accounting and cleanup */
void
connection_exit_about_to_close(edge_connection_t *edge_conn)
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment