Resolve about 24 DOCDOCs

11 files changed, 58 insertions, 32 deletions

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,