Resolve about 24 DOCDOCs

17 files changed, 84 insertions, 44 deletions

diff --git a/src/common/compat.c b/src/common/compat.c
index 629304377f..87fe84cb4b 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 af819dbc97..224c76fda7 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 37c7a148f0..5966e44459 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 634589b1cc..a62c2e6a8c 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 cbc0fb2d2e..c9754418a0 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 ef7095418b..7384f7dc1a 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 ac505c0891..1dce16f5ce 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 992e9af042..86d14bacef 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 9c92dfccdc..f6f97c9182 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 efa872f093..e787ec5c65 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 4d5fdf408e..9ca9239ce5 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 c8dbb2e268..e22ce47b21 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 e401a16123..4722690c15 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 30c8a04c09..02d38e4507 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 cb9a3b1abb..a5addca443 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 3aee0f8bbe..8dcc6eb026 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 b44bd0c426..6308f3a310 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,