[tor-commits] [tor/master] Add about 60 more DOCDOC comments to 0.2.3

commit 173b18c79b8e1f3a28e8b4122adb2b4ccf836c7b Author: Nick Mathewson nickm@torproject.org Date: Mon Jun 4 19:51:00 2012 -0400

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. --- src/common/compat.c | 17 +++++++++++++---- src/common/compat_libevent.c | 7 +++---- src/common/compat_libevent.h | 1 + src/common/crypto.c | 4 +++- src/common/log.c | 1 + src/common/procmon.c | 3 +++ src/common/procmon.h | 1 + src/common/torlog.h | 2 +- src/common/tortls.c | 4 ++++ src/common/util.c | 3 +++ src/common/util.h | 2 ++ src/common/util_codedigest.c | 1 + src/or/buffers.c | 2 +- src/or/circuitbuild.c | 2 ++ src/or/circuitbuild.h | 2 ++ src/or/config.c | 1 + src/or/config_codedigest.c | 1 + src/or/connection.c | 5 ++++- src/or/connection.h | 4 ++++ src/or/connection_edge.c | 4 ++-- src/or/connection_or.c | 2 +- src/or/control.c | 3 +++ src/or/control.h | 2 +- src/or/directory.c | 5 +++-- src/or/dirserv.c | 1 + src/or/dirvote.c | 2 ++ src/or/dirvote.h | 1 - src/or/geoip.c | 1 + src/or/hibernate.c | 2 ++ src/or/main.c | 3 +++ src/or/microdesc.c | 2 +- src/or/networkstatus.c | 6 ++++-- src/or/onion.c | 4 +++- src/or/or.h | 1 + src/or/policies.c | 1 + src/or/relay.c | 3 +++ src/or/rendcommon.c | 1 + src/or/rephist.c | 16 ++++++++++------ src/or/router.c | 1 + src/or/routerlist.c | 7 +++++-- src/or/routerlist.h | 1 + src/or/routerparse.c | 2 ++ 42 files changed, 103 insertions(+), 31 deletions(-)

diff --git a/src/common/compat.c b/src/common/compat.c index 49a4afe..ed6886c 100644 --- a/src/common/compat.c +++ b/src/common/compat.c @@ -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) diff --git a/src/common/compat_libevent.c b/src/common/compat_libevent.c index 70e3baf..e522a8f 100644 --- a/src/common/compat_libevent.c +++ b/src/common/compat_libevent.c @@ -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 diff --git a/src/common/compat_libevent.h b/src/common/compat_libevent.h index 0247297..95f633a 100644 --- a/src/common/compat_libevent.h +++ b/src/common/compat_libevent.h @@ -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; diff --git a/src/common/crypto.c b/src/common/crypto.c index 8feac95..86f19df 100644 --- a/src/common/crypto.c +++ b/src/common/crypto.c @@ -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) { diff --git a/src/common/log.c b/src/common/log.c index f509ddc..f0384a7 100644 --- a/src/common/log.c +++ b/src/common/log.c @@ -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. */ diff --git a/src/common/procmon.c b/src/common/procmon.c index 85d2a2f..4375b60 100644 --- a/src/common/procmon.c +++ b/src/common/procmon.c @@ -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 diff --git a/src/common/procmon.h b/src/common/procmon.h index 02eb2da..3bf6044 100644 --- a/src/common/procmon.h +++ b/src/common/procmon.h @@ -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, diff --git a/src/common/torlog.h b/src/common/torlog.h index 4c5729e..d6b21df 100644 --- a/src/common/torlog.h +++ b/src/common/torlog.h @@ -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, diff --git a/src/common/tortls.c b/src/common/tortls.c index a069ebf..06f6450 100644 --- a/src/common/tortls.c +++ b/src/common/tortls.c @@ -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) { diff --git a/src/common/util.c b/src/common/util.c index b3145ae..e0de262 100644 --- a/src/common/util.c +++ b/src/common/util.c @@ -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) diff --git a/src/common/util.h b/src/common/util.h index ae40898..de22e18 100644 --- a/src/common/util.h +++ b/src/common/util.h @@ -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". */ diff --git a/src/common/util_codedigest.c b/src/common/util_codedigest.c index 88fe508..ef70954 100644 --- a/src/common/util_codedigest.c +++ b/src/common/util_codedigest.c @@ -1,6 +1,7 @@

#include "util.h"

+/** DOCDOC */ const char * libor_get_digests(void) { diff --git a/src/or/buffers.c b/src/or/buffers.c index aa3e01f..cdda5f0 100644 --- a/src/or/buffers.c +++ b/src/or/buffers.c @@ -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? */ diff --git a/src/or/circuitbuild.c b/src/or/circuitbuild.c index 82ff327..cc162f2 100644 --- a/src/or/circuitbuild.c +++ b/src/or/circuitbuild.c @@ -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) { diff --git a/src/or/circuitbuild.h b/src/or/circuitbuild.h index 2ef5be8..27732da 100644 --- a/src/or/circuitbuild.h +++ b/src/or/circuitbuild.h @@ -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);

diff --git a/src/or/config.c b/src/or/config.c index 81d77c3..160ee9a 100644 --- a/src/or/config.c +++ b/src/or/config.c @@ -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. */ diff --git a/src/or/config_codedigest.c b/src/or/config_codedigest.c index be9eaa3..992e9af 100644 --- a/src/or/config_codedigest.c +++ b/src/or/config_codedigest.c @@ -1,6 +1,7 @@

const char *tor_get_digests(void);

+/** DOCDOC */ const char * tor_get_digests(void) { diff --git a/src/or/connection.c b/src/or/connection.c index 3ff6a71..5d32a06 100644 --- a/src/or/connection.c +++ b/src/or/connection.c @@ -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) { diff --git a/src/or/connection.h b/src/or/connection.h index bdeefa2..215eb1b 100644 --- a/src/or/connection.h +++ b/src/or/connection.h @@ -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 diff --git a/src/or/connection_edge.c b/src/or/connection_edge.c index 4c29e06..5ae5b17 100644 --- a/src/or/connection_edge.c +++ b/src/or/connection_edge.c @@ -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) diff --git a/src/or/connection_or.c b/src/or/connection_or.c index fbab666..b5339ad 100644 --- a/src/or/connection_or.c +++ b/src/or/connection_or.c @@ -508,7 +508,7 @@ connection_or_finished_connecting(or_connection_t *or_conn) return 0; }

-/* Called when we're about to finally unlink and free an OR connection: +/** Called when we're about to finally unlink and free an OR connection: * perform necessary accounting and cleanup */ void connection_or_about_to_close(or_connection_t *or_conn) diff --git a/src/or/control.c b/src/or/control.c index 91d94fd..53ea85d 100644 --- a/src/or/control.c +++ b/src/or/control.c @@ -920,10 +920,12 @@ handle_control_loadconf(control_connection_t *conn, uint32_t len, return 0; }

+/* DOCDOC control_event_t */ struct control_event_t { uint16_t event_code; const char *event_name; }; +/* DOCDOC control_event_table */ static const struct control_event_t control_event_table[] = { { EVENT_CIRCUIT_STATUS, "CIRC" }, { EVENT_CIRCUIT_STATUS_MINOR, "CIRC_MINOR" }, @@ -3215,6 +3217,7 @@ is_valid_initial_command(control_connection_t *conn, const char *cmd) * interfaces is broken. */ #define MAX_COMMAND_LINE_LENGTH (1024*1024)

+/* DOCDOC peek_connection_has_control0_command */ static int peek_connection_has_control0_command(connection_t *conn) { diff --git a/src/or/control.h b/src/or/control.h index 7af4449..8786712 100644 --- a/src/or/control.h +++ b/src/or/control.h @@ -50,7 +50,7 @@ int control_event_or_conn_status(or_connection_t *conn, int control_event_bandwidth_used(uint32_t n_read, uint32_t n_written); int control_event_stream_bandwidth(edge_connection_t *edge_conn); int control_event_stream_bandwidth_used(void); -void control_event_logmsg(int severity, unsigned int domain, const char *msg); +void control_event_logmsg(int severity, uint32_t domain, const char *msg); int control_event_descriptors_changed(smartlist_t *routers); int control_event_address_mapped(const char *from, const char *to, time_t expires, const char *error); diff --git a/src/or/directory.c b/src/or/directory.c index 7531260..60a1963 100644 --- a/src/or/directory.c +++ b/src/or/directory.c @@ -2438,7 +2438,8 @@ write_http_response_header(dir_connection_t *conn, ssize_t length, cache_lifetime); }

-#ifdef INSTRUMENT_DOWNLOADS +#if defined(INSTRUMENT_DOWNLOADS) || defined(RUNNING_DOXYGEN) +/* DOCDOC */ typedef struct request_t { uint64_t bytes; /**< How many bytes have we transferred? */ uint64_t count; /**< How many requests have we made? */ @@ -2796,7 +2797,7 @@ directory_handle_command_get(dir_connection_t *conn, const char *headers, want_fps = url+strlen(CONSENSUS_URL_PREFIX); }

- /* XXXX MICRODESC NM NM should check document of correct flavor */ + /* XXXX023 MICRODESC NM NM should check document of correct flavor */ if (v && want_fps && !client_likes_consensus(v, want_fps)) { write_http_status_line(conn, 404, "Consensus not signed by sufficient " diff --git a/src/or/dirserv.c b/src/or/dirserv.c index 1220c32..ec8d9ec 100644 --- a/src/or/dirserv.c +++ b/src/or/dirserv.c @@ -951,6 +951,7 @@ list_single_server_status(const routerinfo_t *desc, int is_live) return tor_strdup(buf); }

+/* DOCDOC running_long_enough_to_decide_unreachable */ static INLINE int running_long_enough_to_decide_unreachable(void) { diff --git a/src/or/dirvote.c b/src/or/dirvote.c index 20dc8c2..e2be239 100644 --- a/src/or/dirvote.c +++ b/src/or/dirvote.c @@ -33,6 +33,7 @@ typedef struct pending_consensus_t { networkstatus_t *consensus; } pending_consensus_t;

+/* DOCDOC dirvote_add_signatures_to_all_pending_consensuses */ static int dirvote_add_signatures_to_all_pending_consensuses( const char *detached_signatures_body, const char *source, @@ -2679,6 +2680,7 @@ static smartlist_t *pending_vote_list = NULL; * build a consensus, the votes go here for the next period. */ static smartlist_t *previous_vote_list = NULL;

+/* DOCDOC pending_consensuses */ static pending_consensus_t pending_consensuses[N_CONSENSUS_FLAVORS];

/** The detached signatures for the consensus that we're currently diff --git a/src/or/dirvote.h b/src/or/dirvote.h index 9248d47..2c8dcff 100644 --- a/src/or/dirvote.h +++ b/src/or/dirvote.h @@ -66,7 +66,6 @@ void set_routerstatus_from_routerinfo(routerstatus_t *rs, routerinfo_t *ri, time_t now, int naming, int listbadexits, int listbaddirs, int vote_on_hsdirs); -void router_clear_status_flags(routerinfo_t *ri); networkstatus_t * dirserv_generate_networkstatus_vote_obj(crypto_pk_t *private_key, authority_cert_t *cert); diff --git a/src/or/geoip.c b/src/or/geoip.c index 5e3735c..7f16a87 100644 --- a/src/or/geoip.c +++ b/src/or/geoip.c @@ -613,6 +613,7 @@ dirreq_map_ent_eq(const dirreq_map_entry_t *a, return a->dirreq_id == b->dirreq_id && a->type == b->type; }

+/* DOCDOC dirreq_map_ent_hash */ static unsigned dirreq_map_ent_hash(const dirreq_map_entry_t *entry) { diff --git a/src/or/hibernate.c b/src/or/hibernate.c index bdf407d..c4a7d37 100644 --- a/src/or/hibernate.c +++ b/src/or/hibernate.c @@ -102,9 +102,11 @@ static time_unit_t cfg_unit = UNIT_MONTH;

/** How many days,hours,minutes into each unit does our accounting interval * start? */ +/** @{ */ static int cfg_start_day = 0, cfg_start_hour = 0, cfg_start_min = 0; +/** @} */

static void reset_accounting(time_t now); static int read_bandwidth_usage(void); diff --git a/src/or/main.c b/src/or/main.c index ab53772..8fbba77 100644 --- a/src/or/main.c +++ b/src/or/main.c @@ -94,7 +94,9 @@ static int stats_prev_global_read_bucket; static int stats_prev_global_write_bucket; #endif

+/* DOCDOC stats_prev_n_read */ static uint64_t stats_prev_n_read = 0; +/* DOCDOC stats_prev_n_written */ static uint64_t stats_prev_n_written = 0;

/* XXX we might want to keep stats about global_relayed_*_bucket too. Or not.*/ @@ -443,6 +445,7 @@ get_bytes_read(void) return stats_n_bytes_read; }

+/* DOCDOC get_bytes_written */ uint64_t get_bytes_written(void) { diff --git a/src/or/microdesc.c b/src/or/microdesc.c index 59b7d7b..7bd0a03 100644 --- a/src/or/microdesc.c +++ b/src/or/microdesc.c @@ -187,7 +187,7 @@ microdescs_add_to_cache(microdesc_cache_t *cache, return added; }

-/* As microdescs_add_to_cache, but takes a list of micrdescriptors instead of +/** As microdescs_add_to_cache, but takes a list of micrdescriptors instead of * a string to decode. Frees any members of <b>descriptors</b> that it does * not add. */ smartlist_t * diff --git a/src/or/networkstatus.c b/src/or/networkstatus.c index 0f51676..029fbe7 100644 --- a/src/or/networkstatus.c +++ b/src/or/networkstatus.c @@ -78,6 +78,7 @@ typedef struct consensus_waiting_for_certs_t { int dl_failed; } consensus_waiting_for_certs_t;

+/* DOCDOC consensus_waiting_for_certs */ static consensus_waiting_for_certs_t consensus_waiting_for_certs[N_CONSENSUS_FLAVORS];

@@ -1006,8 +1007,8 @@ networkstatus_get_v2_list(void) return networkstatus_v2_list; }

-/* As router_get_consensus_status_by_descriptor_digest, but does not return - * a const pointer */ +/** As router_get_consensus_status_by_descriptor_digest, but does not return + * a const pointer. */ routerstatus_t * router_get_mutable_consensus_status_by_descriptor_digest( networkstatus_t *consensus, @@ -2194,6 +2195,7 @@ networkstatus_dump_bridge_status_to_file(time_t now) tor_free(status); }

+/* DOCDOC get_net_param_from_list */ static int32_t get_net_param_from_list(smartlist_t *net_params, const char *param_name, int32_t default_val, int32_t min_val, int32_t max_val) diff --git a/src/or/onion.c b/src/or/onion.c index 09349a4..43f0765 100644 --- a/src/or/onion.c +++ b/src/or/onion.c @@ -29,9 +29,11 @@ typedef struct onion_queue_t { #define ONIONQUEUE_WAIT_CUTOFF 5

/** First and last elements in the linked list of circuits waiting for CPU - * workers, or NULL if the list is empty. */ + * workers, or NULL if the list is empty. + * @{ */ static onion_queue_t *ol_list=NULL; static onion_queue_t *ol_tail=NULL; +/**@}*/ /** Length of ol_list */ static int ol_length=0;

diff --git a/src/or/or.h b/src/or/or.h index 5d620db..a01c14a 100644 --- a/src/or/or.h +++ b/src/or/or.h @@ -1065,6 +1065,7 @@ typedef struct connection_t { uint64_t dirreq_id; } connection_t;

+/* DOCDOC listener_connection_t */ typedef struct listener_connection_t { connection_t _base;

diff --git a/src/or/policies.c b/src/or/policies.c index 5eaebfa..62bdc1e 100644 --- a/src/or/policies.c +++ b/src/or/policies.c @@ -535,6 +535,7 @@ typedef struct policy_map_ent_t { addr_policy_t *policy; } policy_map_ent_t;

+/* DOCDOC policy_root */ static HT_HEAD(policy_map, policy_map_ent_t) policy_root = HT_INITIALIZER();

/** Return true iff a and b are equal. */ diff --git a/src/or/relay.c b/src/or/relay.c index c540d96..003a07f 100644 --- a/src/or/relay.c +++ b/src/or/relay.c @@ -64,6 +64,7 @@ static struct timeval cached_time_hires = {0, 0}; * cells. */ #define CELL_QUEUE_LOWWATER_SIZE 64

+/* DOCDOC tor_gettimeofday_cached */ static void tor_gettimeofday_cached(struct timeval *tv) { @@ -73,6 +74,7 @@ tor_gettimeofday_cached(struct timeval *tv) *tv = cached_time_hires; }

+/* DOCDOC tor_gettimeofday_cache_clear */ void tor_gettimeofday_cache_clear(void) { @@ -2090,6 +2092,7 @@ cell_ewma_get_tick(void) * has value ewma_scale_factor ** N.) */ static double ewma_scale_factor = 0.1; +/* DOCDOC ewma_enabled */ static int ewma_enabled = 0;

#define EPSILON 0.00001 diff --git a/src/or/rendcommon.c b/src/or/rendcommon.c index 20bbdaf..0f78a7b 100644 --- a/src/or/rendcommon.c +++ b/src/or/rendcommon.c @@ -797,6 +797,7 @@ rend_cache_entry_free(rend_cache_entry_t *e) tor_free(e); }

+/* DOCDOC _rend_cache_entry_free */ static void _rend_cache_entry_free(void *p) { diff --git a/src/or/rephist.c b/src/or/rephist.c index 0727c68..e1383bc 100644 --- a/src/or/rephist.c +++ b/src/or/rephist.c @@ -1772,6 +1772,7 @@ rep_hist_load_state(or_state_t *state, char **err)

/*********************************************************************/

+/* DOCDOC predicted_port_t */ typedef struct predicted_port_t { uint16_t port; time_t time; @@ -2745,6 +2746,7 @@ rep_hist_desc_stats_write(time_t now) return start_of_served_descs_stats_interval + WRITE_STATS_INTERVAL; }

+/* DOCDOC rep_hist_note_desc_served */ void rep_hist_note_desc_served(const char * desc) { @@ -2786,27 +2788,27 @@ rep_hist_conn_stats_init(time_t now) * connection stats. */ #define BIDI_INTERVAL 10

-/* Start of next BIDI_INTERVAL second interval. */ +/** Start of next BIDI_INTERVAL second interval. */ static time_t bidi_next_interval = 0;

-/* Number of connections that we read and wrote less than BIDI_THRESHOLD +/** Number of connections that we read and wrote less than BIDI_THRESHOLD * bytes from/to in BIDI_INTERVAL seconds. */ static uint32_t below_threshold = 0;

-/* Number of connections that we read at least BIDI_FACTOR times more +/** Number of connections that we read at least BIDI_FACTOR times more * bytes from than we wrote to in BIDI_INTERVAL seconds. */ static uint32_t mostly_read = 0;

-/* Number of connections that we wrote at least BIDI_FACTOR times more +/** Number of connections that we wrote at least BIDI_FACTOR times more * bytes to than we read from in BIDI_INTERVAL seconds. */ static uint32_t mostly_written = 0;

-/* Number of connections that we read and wrote at least BIDI_THRESHOLD +/** Number of connections that we read and wrote at least BIDI_THRESHOLD * bytes from/to, but not BIDI_FACTOR times more in either direction in * BIDI_INTERVAL seconds. */ static uint32_t both_read_and_written = 0;

-/* Entry in a map from connection ID to the number of read and written +/** Entry in a map from connection ID to the number of read and written * bytes on this connection in a BIDI_INTERVAL second interval. */ typedef struct bidi_map_entry_t { HT_ENTRY(bidi_map_entry_t) node; @@ -2826,6 +2828,7 @@ bidi_map_ent_eq(const bidi_map_entry_t *a, const bidi_map_entry_t *b) return a->conn_id == b->conn_id; }

+/* DOCDOC bidi_map_ent_hash */ static unsigned bidi_map_ent_hash(const bidi_map_entry_t *entry) { @@ -2837,6 +2840,7 @@ HT_PROTOTYPE(bidimap, bidi_map_entry_t, node, bidi_map_ent_hash, HT_GENERATE(bidimap, bidi_map_entry_t, node, bidi_map_ent_hash, bidi_map_ent_eq, 0.6, malloc, realloc, free);

+/* DOCDOC bidi_map_free */ static void bidi_map_free(void) { diff --git a/src/or/router.c b/src/or/router.c index 34e231a..fc7cf73 100644 --- a/src/or/router.c +++ b/src/or/router.c @@ -484,6 +484,7 @@ v3_authority_check_key_expiry(void) last_warned = now; }

+/* DOCDOC router_initialize_tls_context */ int router_initialize_tls_context(void) { diff --git a/src/or/routerlist.c b/src/or/routerlist.c index 5586439..9e5fff4 100644 --- a/src/or/routerlist.c +++ b/src/or/routerlist.c @@ -104,9 +104,12 @@ static time_t last_descriptor_download_attempted = 0; /** When we last computed the weights to use for bandwidths on directory * requests, what were the total weighted bandwidth, and our share of that * bandwidth? Used to determine what fraction of directory requests we should - * expect to see. */ + * expect to see. + * + * @{ */ static uint64_t sl_last_total_weighted_bw = 0, sl_last_weighted_bw_of_me = 0; +/**@}*/

/** Return the number of directory authorities whose type matches some bit set * in <b>type</b> */ @@ -2294,7 +2297,7 @@ hex_digest_nickname_matches(const char *hexdigest, const char *identity_digest, return tor_memeq(digest, identity_digest, DIGEST_LEN); }

-/* Return true iff <b>router</b> is listed as named in the current +/** Return true iff <b>router</b> is listed as named in the current * consensus. */ int router_is_named(const routerinfo_t *router) diff --git a/src/or/routerlist.h b/src/or/routerlist.h index cae8814..ee665b6 100644 --- a/src/or/routerlist.h +++ b/src/or/routerlist.h @@ -103,6 +103,7 @@ static INLINE int WRA_WAS_OUTDATED(was_router_added_t s) s == ROUTER_NOT_IN_CONSENSUS || s == ROUTER_NOT_IN_CONSENSUS_OR_NETWORKSTATUS); } +/* DOCDOC WRA_WAS_REJECTED */ static INLINE int WRA_WAS_REJECTED(was_router_added_t s) { return (s == ROUTER_AUTHDIR_REJECTS); diff --git a/src/or/routerparse.c b/src/or/routerparse.c index d86c0cf..dbc6bf1 100644 --- a/src/or/routerparse.c +++ b/src/or/routerparse.c @@ -519,6 +519,7 @@ static token_rule_t networkstatus_detached_signature_token_table[] = { END_OF_TABLE };

+/* DOCDOC microdesc_token_table */ static token_rule_t microdesc_token_table[] = { T1_START("onion-key", K_ONION_KEY, NO_ARGS, NEED_KEY_1024), T01("family", K_FAMILY, ARGS, NO_OBJ ), @@ -4200,6 +4201,7 @@ find_all_exitpolicy(smartlist_t *s) return out; }

+/* DOCDOC router_get_hash_impl_helper */ static int router_get_hash_impl_helper(const char *s, size_t s_len, const char *start_str,