commit 913067f788d84d748d9377bb5563b2a8f88dc483
Author: Nick Mathewson <nickm(a)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,
