[tor-commits] [tor/master] Resolve about 24 DOCDOCs

commit 913067f788d84d748d9377bb5563b2a8f88dc483 Author: Nick Mathewson nickm@torproject.org Date: Tue Jun 5 00:17:54 2012 -0400

Resolve about 24 DOCDOCs --- src/common/compat.c | 7 ++++++- src/common/compat_libevent.h | 7 ++++++- src/common/log.c | 2 +- src/common/tortls.c | 18 +++++++++++------- src/common/util.h | 1 - src/common/util_codedigest.c | 3 ++- src/or/config.c | 3 ++- src/or/config_codedigest.c | 3 ++- src/or/control.c | 10 +++++++--- src/or/networkstatus.c | 4 +++- src/or/or.h | 2 +- src/or/relay.c | 7 +++++-- src/or/rendcommon.c | 3 ++- src/or/rephist.c | 6 +++++- src/or/router.c | 3 ++- src/or/routerlist.h | 11 +++++++---- src/or/routerparse.c | 38 ++++++++++++++++++++++---------------- 17 files changed, 84 insertions(+), 44 deletions(-)

diff --git a/src/common/compat.c b/src/common/compat.c index 6293043..87fe84c 100644 --- a/src/common/compat.c +++ b/src/common/compat.c @@ -2364,7 +2364,12 @@ tor_gettimeofday(struct timeval *timeval) #define TIME_FNS_NEED_LOCKS #endif

-/* DOCDOC correct_tm */ +/** Helper: Deal with confused or out-of-bounds values from localtime_r and + * friends. (On some platforms, they can give out-of-bounds values or can + * return NULL.) If <b>islocal</b>, this is a localtime result; otherwise + * it's from gmtime. The function returned <b>r</b>, when given <b>timep</b> + * as its input. If we need to store new results, store them in + * <b>resultbuf</b>. */ static struct tm * correct_tm(int islocal, const time_t *timep, struct tm *resultbuf, struct tm *r) diff --git a/src/common/compat_libevent.h b/src/common/compat_libevent.h index af819db..224c76f 100644 --- a/src/common/compat_libevent.h +++ b/src/common/compat_libevent.h @@ -59,10 +59,15 @@ struct timeval; int tor_event_base_loopexit(struct event_base *base, struct timeval *tv); #endif

-/* DOCDOC tor_libevent_cfg */ +/** Defines a configuration for using libevent with Tor: passed as an argument + * to tor_libevent_initialize() to describe how we want to set up. */ typedef struct tor_libevent_cfg { + /** Flag: if true, disable IOCP (assuming that it could be enabled). */ int disable_iocp; + /** How many CPUs should we use (relevant only with IOCP). */ int num_cpus; + /** How many milliseconds should we allow between updating bandwidth limits? + * (relevant only with bufferevents). */ int msec_per_tick; } tor_libevent_cfg;

diff --git a/src/common/log.c b/src/common/log.c index 37c7a14..5966e44 100644 --- a/src/common/log.c +++ b/src/common/log.c @@ -97,7 +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 */ +/** True iff we have initialized log_mutex */ static int log_mutex_initialized = 0;

/** Linked list of logfile_t. */ diff --git a/src/common/tortls.c b/src/common/tortls.c index 634589b..a62c2e6 100644 --- a/src/common/tortls.c +++ b/src/common/tortls.c @@ -223,10 +223,12 @@ static int check_cert_lifetime_internal(int severity, const X509 *cert, int past_tolerance, int future_tolerance);

/** Global TLS contexts. We keep them here because nobody else needs - * to touch them. */ + * 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. */ static int tls_library_is_initialized = 0; @@ -269,7 +271,9 @@ 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 */ +/** Log a single error <b>err</b> as returned by ERR_get_error(), which was + * received while performing an operation <b>doing</b> on <b>tls</b>. Log + * the message at <b>severity</b>, in log domain <b>domain</b>. */ void tor_tls_log_one_error(tor_tls_t *tls, unsigned long err, int severity, int domain, const char *doing) @@ -314,8 +318,8 @@ tor_tls_log_one_error(tor_tls_t *tls, unsigned long err, } }

-/** Log all pending tls errors at level <b>severity</b>. Use - * <b>doing</b> to describe our current activities. +/** Log all pending tls errors at level <b>severity</b> in log domain + * <b>domain</b>. Use <b>doing</b> to describe our current activities. */ static void tls_log_errors(tor_tls_t *tls, int severity, int domain, const char *doing) @@ -1344,7 +1348,7 @@ tor_tls_client_is_using_v2_ciphers(const SSL *ssl, const char *address) return 1; }

-/* DOCDOC tor_tls_debug_state_callback */ +/** Invoked when a TLS state changes: log the change at severity 'debug' */ static void tor_tls_debug_state_callback(const SSL *ssl, int type, int val) { @@ -1624,7 +1628,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 */ +/** Assert that the flags that allow legacy renegotiation are still set */ void tor_tls_assert_renegotiation_unblocked(tor_tls_t *tls) { diff --git a/src/common/util.h b/src/common/util.h index cbc0fb2..c975441 100644 --- a/src/common/util.h +++ b/src/common/util.h @@ -72,7 +72,6 @@ /* 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); diff --git a/src/common/util_codedigest.c b/src/common/util_codedigest.c index ef70954..7384f7d 100644 --- a/src/common/util_codedigest.c +++ b/src/common/util_codedigest.c @@ -1,7 +1,8 @@

#include "util.h"

-/** DOCDOC */ +/** Return a string describing the digest of the source files in src/common/ + */ const char * libor_get_digests(void) { diff --git a/src/or/config.c b/src/or/config.c index ac505c0..1dce16f 100644 --- a/src/or/config.c +++ b/src/or/config.c @@ -786,7 +786,8 @@ 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 */ +/** A shorter version of this Tor process's version, for export in our router + * descriptor. (Does not include the git version, if any.) */ 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 992e9af..86d14ba 100644 --- a/src/or/config_codedigest.c +++ b/src/or/config_codedigest.c @@ -1,7 +1,8 @@

const char *tor_get_digests(void);

-/** DOCDOC */ +/** Return a string describing the digest of the source files in src/or/ + */ const char * tor_get_digests(void) { diff --git a/src/or/control.c b/src/or/control.c index 9c92dfc..f6f97c9 100644 --- a/src/or/control.c +++ b/src/or/control.c @@ -920,12 +920,13 @@ handle_control_loadconf(control_connection_t *conn, uint32_t len, return 0; }

-/* DOCDOC control_event_t */ +/** Helper structure: maps event values to their names. */ struct control_event_t { uint16_t event_code; const char *event_name; }; -/* DOCDOC control_event_table */ +/** Table mapping event values to their names. Used to implement SETEVENTS + * and GETINFO events/names, and to keep they in sync. */ static const struct control_event_t control_event_table[] = { { EVENT_CIRCUIT_STATUS, "CIRC" }, { EVENT_CIRCUIT_STATUS_MINOR, "CIRC_MINOR" }, @@ -3217,7 +3218,10 @@ 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 */ +/** Wrapper around peek_(evbuffer|buf)_has_control0 command: presents the same + * interface as those underlying functions, but takes a connection_t intead of + * an evbuffer or a buf_t. + */ static int peek_connection_has_control0_command(connection_t *conn) { diff --git a/src/or/networkstatus.c b/src/or/networkstatus.c index efa872f..e787ec5 100644 --- a/src/or/networkstatus.c +++ b/src/or/networkstatus.c @@ -78,7 +78,9 @@ typedef struct consensus_waiting_for_certs_t { int dl_failed; } consensus_waiting_for_certs_t;

-/* DOCDOC consensus_waiting_for_certs */ +/** An array, for each flavor of consensus we might want, of consensuses that + * we have downloaded, but which we cannot verify due to having insufficient + * authority certificates. */ static consensus_waiting_for_certs_t consensus_waiting_for_certs[N_CONSENSUS_FLAVORS];

diff --git a/src/or/or.h b/src/or/or.h index 4d5fdf4..9ca9239 100644 --- a/src/or/or.h +++ b/src/or/or.h @@ -1065,7 +1065,7 @@ typedef struct connection_t { uint64_t dirreq_id; } connection_t;

-/* DOCDOC listener_connection_t */ +/** Subtype of connection_t; used for a listener socket. */ typedef struct listener_connection_t { connection_t _base;

diff --git a/src/or/relay.c b/src/or/relay.c index c8dbb2e..e22ce47 100644 --- a/src/or/relay.c +++ b/src/or/relay.c @@ -64,7 +64,7 @@ static struct timeval cached_time_hires = {0, 0}; * cells. */ #define CELL_QUEUE_LOWWATER_SIZE 64

-/* DOCDOC tor_gettimeofday_cached */ +/** Return a fairly recent view of the current time. */ static void tor_gettimeofday_cached(struct timeval *tv) { @@ -74,7 +74,8 @@ tor_gettimeofday_cached(struct timeval *tv) *tv = cached_time_hires; }

-/* DOCDOC tor_gettimeofday_cache_clear */ +/** Reset the cached view of the current time, so that the next time we try + * to learn it, we will get an up-to-date value. */ void tor_gettimeofday_cache_clear(void) { @@ -2095,7 +2096,9 @@ static double ewma_scale_factor = 0.1; /* DOCDOC ewma_enabled */ static int ewma_enabled = 0;

+/*DOCDOC*/ #define EPSILON 0.00001 +/*DOCDOC*/ #define LOG_ONEHALF -0.69314718055994529

/** Adjust the global cell scale factor based on <b>options</b> */ diff --git a/src/or/rendcommon.c b/src/or/rendcommon.c index e401a16..4722690 100644 --- a/src/or/rendcommon.c +++ b/src/or/rendcommon.c @@ -797,7 +797,8 @@ rend_cache_entry_free(rend_cache_entry_t *e) tor_free(e); }

-/* DOCDOC _rend_cache_entry_free */ +/** Helper: deallocate a rend_cache_entry_t. (Used with strmap_free(), which + * requires a function pointer whose argument is void*). */ static void _rend_cache_entry_free(void *p) { diff --git a/src/or/rephist.c b/src/or/rephist.c index 30c8a04..02d38e4 100644 --- a/src/or/rephist.c +++ b/src/or/rephist.c @@ -1772,9 +1772,13 @@ rep_hist_load_state(or_state_t *state, char **err)

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

-/* DOCDOC predicted_port_t */ +/** A single predicted port: used to remember which ports we've made + * connections to, so that we can try to keep making circuits that can handle + * those ports. */ typedef struct predicted_port_t { + /** The port we connected to */ uint16_t port; + /** The time at which we last used it */ time_t time; } predicted_port_t;

diff --git a/src/or/router.c b/src/or/router.c index cb9a3b1..a5addca 100644 --- a/src/or/router.c +++ b/src/or/router.c @@ -484,7 +484,8 @@ v3_authority_check_key_expiry(void) last_warned = now; }

-/* DOCDOC router_initialize_tls_context */ +/** Set up Tor's TLS contexts, based on our configuration and keys. Return 0 + * on success, and -1 on failure. */ int router_initialize_tls_context(void) { diff --git a/src/or/routerlist.h b/src/or/routerlist.h index 3aee0f8..8dcc6eb 100644 --- a/src/or/routerlist.h +++ b/src/or/routerlist.h @@ -85,14 +85,16 @@ void router_set_status(const char *digest, int up); static int WRA_WAS_ADDED(was_router_added_t s); static int WRA_WAS_OUTDATED(was_router_added_t s); static int WRA_WAS_REJECTED(was_router_added_t s); -/** Return true iff the descriptor was added. It might still be necessary to - * check whether the descriptor generator should be notified. +/** Return true iff the outcome code in <b>s</b> indicates that the descriptor + * was added. It might still be necessary to check whether the descriptor + * generator should be notified. */ static INLINE int WRA_WAS_ADDED(was_router_added_t s) { return s == ROUTER_ADDED_SUCCESSFULLY || s == ROUTER_ADDED_NOTIFY_GENERATOR; } -/** Return true iff the descriptor was not added because it was either: +/** Return true iff the outcome code in <b>s</b> indicates that the descriptor + * was not added because it was either: * - not in the consensus * - neither in the consensus nor in any networkstatus document * - it was outdated. @@ -103,7 +105,8 @@ 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 */ +/** Return true iff the outcome code in <b>s</b> indicates that the descriptor + * was flat-out 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 b44bd0c..6308f3a 100644 --- a/src/or/routerparse.c +++ b/src/or/routerparse.c @@ -263,7 +263,7 @@ typedef struct token_rule_t { /* Argument multiplicity: exactly <b>n</b> arguments. */ #define EQ(n) n,n,0

-/** List of tokens allowable in router descriptors */ +/** List of tokens recognized in router descriptors */ static token_rule_t routerdesc_token_table[] = { T0N("reject", K_REJECT, ARGS, NO_OBJ ), T0N("accept", K_ACCEPT, ARGS, NO_OBJ ), @@ -296,7 +296,7 @@ static token_rule_t routerdesc_token_table[] = { END_OF_TABLE };

-/** List of tokens allowable in extra-info documents. */ +/** List of tokens recognized in extra-info documents. */ static token_rule_t extrainfo_token_table[] = { T1_END( "router-signature", K_ROUTER_SIGNATURE, NO_ARGS, NEED_OBJ ), T1( "published", K_PUBLISHED, CONCAT_ARGS, NO_OBJ ), @@ -333,7 +333,7 @@ static token_rule_t extrainfo_token_table[] = { END_OF_TABLE };

-/** List of tokens allowable in the body part of v2 and v3 networkstatus +/** List of tokens recognized in the body part of v2 and v3 networkstatus * documents. */ static token_rule_t rtrstatus_token_table[] = { T01("p", K_P, CONCAT_ARGS, NO_OBJ ), @@ -346,7 +346,7 @@ static token_rule_t rtrstatus_token_table[] = { END_OF_TABLE };

-/** List of tokens allowable in the header part of v2 networkstatus documents. +/** List of tokens recognized in the header part of v2 networkstatus documents. */ static token_rule_t netstatus_token_table[] = { T1( "published", K_PUBLISHED, CONCAT_ARGS, NO_OBJ ), @@ -364,14 +364,14 @@ static token_rule_t netstatus_token_table[] = { END_OF_TABLE };

-/** List of tokens allowable in the footer of v1/v2 directory/networkstatus +/** List of tokens recognized in the footer of v1/v2 directory/networkstatus * footers. */ static token_rule_t dir_footer_token_table[] = { T1("directory-signature", K_DIRECTORY_SIGNATURE, EQ(1), NEED_OBJ ), END_OF_TABLE };

-/** List of tokens allowable in v1 directory headers/footers. */ +/** List of tokens recognized in v1 directory headers/footers. */ static token_rule_t dir_token_table[] = { /* don't enforce counts; this is obsolete. */ T( "network-status", K_NETWORK_STATUS, NO_ARGS, NO_OBJ ), @@ -403,14 +403,14 @@ static token_rule_t dir_token_table[] = { NO_ARGS, NEED_OBJ), \ T01("dir-address", K_DIR_ADDRESS, GE(1), NO_OBJ),

-/** List of tokens allowable in V3 authority certificates. */ +/** List of tokens recognized in V3 authority certificates. */ static token_rule_t dir_key_certificate_table[] = { CERTIFICATE_MEMBERS T1("fingerprint", K_FINGERPRINT, CONCAT_ARGS, NO_OBJ ), END_OF_TABLE };

-/** List of tokens allowable in rendezvous service descriptors */ +/** List of tokens recognized in rendezvous service descriptors */ static token_rule_t desc_token_table[] = { T1_START("rendezvous-service-descriptor", R_RENDEZVOUS_SERVICE_DESCRIPTOR, EQ(1), NO_OBJ), @@ -424,7 +424,7 @@ static token_rule_t desc_token_table[] = { END_OF_TABLE };

-/** List of tokens allowed in the (encrypted) list of introduction points of +/** List of tokens recognized in the (encrypted) list of introduction points of * rendezvous service descriptors */ static token_rule_t ipo_token_table[] = { T1_START("introduction-point", R_IPO_IDENTIFIER, EQ(1), NO_OBJ), @@ -435,7 +435,7 @@ static token_rule_t ipo_token_table[] = { END_OF_TABLE };

-/** List of tokens allowed in the (possibly encrypted) list of introduction +/** List of tokens recognized in the (possibly encrypted) list of introduction * points of rendezvous service descriptors */ static token_rule_t client_keys_token_table[] = { T1_START("client-name", C_CLIENT_NAME, CONCAT_ARGS, NO_OBJ), @@ -444,7 +444,7 @@ static token_rule_t client_keys_token_table[] = { END_OF_TABLE };

-/** List of tokens allowed in V3 networkstatus votes. */ +/** List of tokens recognized in V3 networkstatus votes. */ static token_rule_t networkstatus_token_table[] = { T1_START("network-status-version", K_NETWORK_STATUS_VERSION, GE(1), NO_OBJ ), @@ -472,7 +472,7 @@ static token_rule_t networkstatus_token_table[] = { END_OF_TABLE };

-/** List of tokens allowed in V3 networkstatus consensuses. */ +/** List of tokens recognized in V3 networkstatus consensuses. */ static token_rule_t networkstatus_consensus_token_table[] = { T1_START("network-status-version", K_NETWORK_STATUS_VERSION, GE(1), NO_OBJ ), @@ -498,7 +498,7 @@ static token_rule_t networkstatus_consensus_token_table[] = { END_OF_TABLE };

-/** List of tokens allowable in the footer of v1/v2 directory/networkstatus +/** List of tokens recognized in the footer of v1/v2 directory/networkstatus * footers. */ static token_rule_t networkstatus_vote_footer_token_table[] = { T01("directory-footer", K_DIRECTORY_FOOTER, NO_ARGS, NO_OBJ ), @@ -507,7 +507,7 @@ static token_rule_t networkstatus_vote_footer_token_table[] = { END_OF_TABLE };

-/** List of tokens allowable in detached networkstatus signature documents. */ +/** List of tokens recognized in detached networkstatus signature documents. */ static token_rule_t networkstatus_detached_signature_token_table[] = { T1_START("consensus-digest", K_CONSENSUS_DIGEST, GE(1), NO_OBJ ), T("additional-digest", K_ADDITIONAL_DIGEST,GE(3), NO_OBJ ), @@ -519,7 +519,7 @@ static token_rule_t networkstatus_detached_signature_token_table[] = { END_OF_TABLE };

-/* DOCDOC microdesc_token_table */ +/** List of tokens recognized in microdescriptors */ 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 ), @@ -4201,7 +4201,13 @@ find_all_exitpolicy(smartlist_t *s) return out; }

-/* DOCDOC router_get_hash_impl_helper */ +/** Helper function for <b>router_get_hash_impl</b>: given <b>s</b>, + * <b>s_len</b>, <b>start_str</b>, <b>end_str</b>, and <b>end_c</b> with the + * same semantics as in that function, set *<b>start_out</b> (inclusive) and + * *<b>end_out</b> (exclusive) to the boundaries of the string to be hashed. + * + * Return 0 on success and -1 on failure. + */ static int router_get_hash_impl_helper(const char *s, size_t s_len, const char *start_str,