Fix most DOCDOCs remaining and/or added by redox.

svn:r17734

15 files changed, 178 insertions, 101 deletions

diff --git a/src/or/buffers.c b/src/or/buffers.c
index 141fe58b12..f070755310 100644
--- a/src/or/buffers.c
+++ b/src/or/buffers.c
@@ -549,7 +549,8 @@ buf_add_chunk_with_capacity(buf_t *buf, size_t capacity, int capped)
   return chunk;
 }
 
-/** DOCDOC */
+/** If we're using readv and writev, how many chunks are we willing to
+ * read/write at a time? */
 #define N_IOV 3
 
 /** Read up to <b>at_most</b> bytes from the socket <b>fd</b> into
diff --git a/src/or/connection.c b/src/or/connection.c
index b30cbe2acd..7bcf65539e 100644
--- a/src/or/connection.c
+++ b/src/or/connection.c
@@ -153,7 +153,8 @@ conn_state_to_string(int type, int state)
   return buf;
 }
 
-/* DOCDOC dir_connection_new */
+/** Allocate and return a new dir_connection_t, initialized as by
+ * connection_init(). */
 dir_connection_t *
 dir_connection_new(int socket_family)
 {
@@ -161,7 +162,9 @@ dir_connection_new(int socket_family)
   connection_init(time(NULL), TO_CONN(dir_conn), CONN_TYPE_DIR, socket_family);
   return dir_conn;
 }
-/* DOCDOC or_connection_new */
+
+/** Allocate and return a new or_connection_t, initialized as by
+ * connection_init(). */
 or_connection_t *
 or_connection_new(int socket_family)
 {
@@ -174,7 +177,9 @@ or_connection_new(int socket_family)
 
   return or_conn;
 }
-/* DOCDOC edge_connection_new */
+
+/** Allocate and return a new edge_connection_t, initialized as by
+ * connection_init(). */
 edge_connection_t *
 edge_connection_new(int type, int socket_family)
 {
@@ -185,7 +190,9 @@ edge_connection_new(int type, int socket_family)
     edge_conn->socks_request = tor_malloc_zero(sizeof(socks_request_t));
   return edge_conn;
 }
-/* DOCDOC control_connection_new */
+
+/** Allocate and return a new control_connection_t, initialized as by
+ * connection_init(). */
 control_connection_t *
 control_connection_new(int socket_family)
 {
@@ -196,7 +203,9 @@ control_connection_new(int socket_family)
   return control_conn;
 }
 
-/* DOCDOC connection_new */
+/** Allocate, initialize, and return a new connection_t subtype of <b>type</b>
+ * to make or receive connections of address family <b>socket_family</b>.  The
+ * type should be one of the CONN_TYPE_* constants. */
 connection_t *
 connection_new(int type, int socket_family)
 {
@@ -811,7 +820,9 @@ create_unix_sockaddr(const char *listenaddress, char **readable_address)
 };
 #endif /* HAVE_SYS_UN_H */
 
-/* DOCDOC warn_too_many_conns */
+/** Warn that an accept or a connect has failed because we're running up
+ * against our ulimit.  Rate-limit these warnings so that we don't spam
+ * the log. */
 static void
 warn_too_many_conns(void)
 {
diff --git a/src/or/control.c b/src/or/control.c
index fafa1c1e5a..d807eb5d63 100644
--- a/src/or/control.c
+++ b/src/or/control.c
@@ -83,13 +83,25 @@ static char authentication_cookie[AUTHENTICATION_COOKIE_LEN];
  * of this so we can respond to getinfo status/bootstrap-phase queries. */
 static char last_sent_bootstrap_message[BOOTSTRAP_MSG_LEN];
 
+/** Flag for event_format_t.  Indicates that we should use the old
+ * name format of nickname|hexdigest
+ */
 #define SHORT_NAMES 1
+/** Flag for event_format_t.  Indicates that we should use the new
+ * name format of $hexdigest[=~]nickname
+ */
 #define LONG_NAMES 2
 #define ALL_NAMES (SHORT_NAMES|LONG_NAMES)
+/** Flag for event_format_t.  Indicates that we should use the new event
+ * format where extra event fields are allowed using a NAME=VAL format. */
 #define EXTENDED_FORMAT 4
+/** Flag for event_format_t.  Indicates that we are using the old event format
+ * where extra fields aren't allowed. */
 #define NONEXTENDED_FORMAT 8
 #define ALL_FORMATS (EXTENDED_FORMAT|NONEXTENDED_FORMAT)
-/* DOCDOC event_format_t */
+
+/** Bit field of flags to select how to format a controller event.  Recognized
+ * flags are SHORT_NAMES, LONG_NAMES, EXTENDED_FORMAT, NONEXTENDED_FORMAT. */
 typedef int event_format_t;
 
 static void connection_printf_to_buf(control_connection_t *conn,
diff --git a/src/or/directory.c b/src/or/directory.c
index b5475fe6de..7a0db89eda 100644
--- a/src/or/directory.c
+++ b/src/or/directory.c
@@ -862,18 +862,17 @@ _compare_strs(const void **a, const void **b)
   return strcmp(s1, s2);
 }
 
+#define CONDITIONAL_CONSENSUS_FPR_LEN 3
+#if (CONDITIONAL_CONSENSUS_FPR_LEN > DIGEST_LEN)
+#error "conditional consensus fingerprint length is larger than digest length"
+#endif
+
 /** Return the URL we should use for a consensus download.
  *
  * This url depends on whether or not the server we go to
  * is sufficiently new to support conditional consensus downloading,
  * i.e. GET .../consensus/<b>fpr</b>+<b>fpr</b>+<b>fpr</b>
  */
-#define CONDITIONAL_CONSENSUS_FPR_LEN 3
-#if (CONDITIONAL_CONSENSUS_FPR_LEN > DIGEST_LEN)
-#error "conditional consensus fingerprint length is larger than digest length"
-#endif
-
-/* DOCDOC directory_get_consensus_url */
 static char *
 directory_get_consensus_url(int supports_conditional_consensus)
 {
@@ -2195,7 +2194,10 @@ typedef struct request_t {
  * of request.  Maps from request type to pointer to request_t. */
 static strmap_t *request_map = NULL;
 
-/* DOCDOC note_client_request */
+/** Record that a client request of <b>purpose</b> was made, and that
+ * <b>bytes</b> bytes of possibly <b>compressed</b> data were sent/received.
+ * Used to keep track of how much we've up/downloaded in what kind of
+ * request. */
 static void
 note_client_request(int purpose, int compressed, size_t bytes)
 {
diff --git a/src/or/dirserv.c b/src/or/dirserv.c
index 3fd6b7a566..2d9327bf28 100644
--- a/src/or/dirserv.c
+++ b/src/or/dirserv.c
@@ -1587,7 +1587,8 @@ dirserv_get_runningrouters(void)
                          "v1 network status list", V1_AUTHORITY);
 }
 
-/* DOCDOC */
+/** Return the latest downloaded consensus networkstatus in encoded, signed,
+ * optionally compressed format, suitable for sending to clients. */
 cached_dir_t *
 dirserv_get_consensus(void)
 {
diff --git a/src/or/dirvote.c b/src/or/dirvote.c
index da34ab1dcf..b276b11fca 100644
--- a/src/or/dirvote.c
+++ b/src/or/dirvote.c
@@ -219,7 +219,9 @@ get_voter(const networkstatus_t *vote)
   return smartlist_get(vote->voters, 0);
 }
 
-/* DOCDOC dir_src_ent_t */
+/** Temporary structure used in constructing a list of dir-source entries
+ * for a consensus.  One of these is generated for every vote, and one more
+ * for every legacy key in each vote. */
 typedef struct dir_src_ent_t {
   networkstatus_t *v;
   const char *digest;
@@ -236,7 +238,9 @@ _compare_votes_by_authority_id(const void **_a, const void **_b)
                 get_voter(b)->identity_digest, DIGEST_LEN);
 }
 
-/* DOCDOC _compare_dir_src_ents_by_authority_id */
+/** Helper: Compare the dir_src_ent_ts in *<b>_a</b> and *<b>_b</b> by
+ * their identity digests, and return -1, 0, or 1 depending on their
+ * ordering */
 static int
 _compare_dir_src_ents_by_authority_id(const void **_a, const void **_b)
 {
diff --git a/src/or/dns.c b/src/or/dns.c
index 271e348afd..26cd02d543 100644
--- a/src/or/dns.c
+++ b/src/or/dns.c
@@ -186,9 +186,10 @@ evdns_log_cb(int warn, const char *msg)
   log(severity, LD_EXIT, "eventdns: %s", msg);
 }
 
-/* DOCDOC randfn */
+/** Helper: passed to eventdns.c as a callback so it can generate random
+ * numbers for transaction IDs and 0x20-hack coding. */
 static void
-randfn(char *b, size_t n)
+_dns_randfn(char *b, size_t n)
 {
   crypto_rand(b,n);
 }
@@ -198,7 +199,7 @@ int
 dns_init(void)
 {
   init_cache_map();
-  evdns_set_random_bytes_fn(randfn);
+  evdns_set_random_bytes_fn(_dns_randfn);
   if (get_options()->ServerDNSRandomizeCase)
     evdns_set_option("randomize-case", "1", DNS_OPTIONS_ALL);
   else
diff --git a/src/or/geoip.c b/src/or/geoip.c
index a0ac6039f2..65d03aec69 100644
--- a/src/or/geoip.c
+++ b/src/or/geoip.c
@@ -438,7 +438,8 @@ _c_hist_compare(const void **_a, const void **_b)
  * are willing to talk about it? */
 #define GEOIP_MIN_OBSERVATION_TIME (12*60*60)
 
-/* DOCDOC round_to_next_multiple_of */
+/** Return the lowest x such that x is at least <b>number</b>, and x modulo
+ * <b>divisor</b> == 0. */
 static INLINE unsigned
 round_to_next_multiple_of(unsigned number, unsigned divisor)
 {
@@ -589,7 +590,7 @@ geoip_get_request_history(time_t now, geoip_client_action_t action)
   return result;
 }
 
-/* DOCDOC dump_geoip_stats */
+/** Store all our geoip statistics into $DATADIR/geoip-stats. */
 void
 dump_geoip_stats(void)
 {
diff --git a/src/or/main.c b/src/or/main.c
index 63f538300d..485ef4c686 100644
--- a/src/or/main.c
+++ b/src/or/main.c
@@ -1902,14 +1902,14 @@ try_locking(or_options_t *options, int err_if_locked)
   }
 }
 
-/* DOCDOC have_lockfile */
+/** Return true iff we've successfully acquired the lock file. */
 int
 have_lockfile(void)
 {
   return lockfile != NULL;
 }
 
-/* DOCDOC release_lockfile */
+/** If we have successfully acquired the lock file, release it. */
 void
 release_lockfile(void)
 {
diff --git a/src/or/policies.c b/src/or/policies.c
index a9553774b4..ece48b16e3 100644
--- a/src/or/policies.c
+++ b/src/or/policies.c
@@ -235,7 +235,10 @@ addr_policy_permits_tor_addr(const tor_addr_t *addr, uint16_t port,
   }
 }
 
-/* DOCDOC XXXX deprecate when possible. */
+/** Return true iff <b> policy</b> (possibly NULL) will allow a connection to
+ * <b>addr</b>:<b>port</b>.  <b>addr</b> is an IPv4 address given in host
+ * order. */
+/* XXXX deprecate when possible. */
 static int
 addr_policy_permits_address(uint32_t addr, uint16_t port,
                             smartlist_t *policy)
@@ -254,7 +257,8 @@ fascist_firewall_allows_address_or(const tor_addr_t *addr, uint16_t port)
                                      reachable_or_addr_policy);
 }
 
-/** DOCDOC */
+/** Return true iff we think our firewall will let us make an OR connection to
+ * <b>ri</b>. */
 int
 fascist_firewall_allows_or(routerinfo_t *ri)
 {
@@ -552,7 +556,8 @@ addr_policy_get_canonical_entry(addr_policy_t *e)
   return found->policy;
 }
 
-/** DOCDOC */
+/** As compare_to_addr_to_addr_policy, but instead of a tor_addr_t, takes
+ * in host order. */
 addr_policy_result_t
 compare_addr_to_addr_policy(uint32_t addr, uint16_t port, smartlist_t *policy)
 {
diff --git a/src/or/relay.c b/src/or/relay.c
index 3071f16a58..2e114eb478 100644
--- a/src/or/relay.c
+++ b/src/or/relay.c
@@ -1470,7 +1470,9 @@ packed_cell_alloc(void)
   ++total_cells_allocated;
   return mp_pool_get(cell_pool);
 }
-/* DOCDOC dump_cell_pool_usage */
+
+/** Log current statistics for cell pool allocation at log level
+ * <b>severity</b>. */
 void
 dump_cell_pool_usage(int severity)
 {
diff --git a/src/or/router.c b/src/or/router.c
index 7c4226f969..c2d7f9d0b9 100644
--- a/src/or/router.c
+++ b/src/or/router.c
@@ -149,14 +149,17 @@ get_my_v3_authority_signing_key(void)
   return authority_signing_key;
 }
 
-/* DOCDOC get_my_v3_legacy_cert */
+/** If we're an authority, and we're using a legacy authority identity key for
+ * emergency migration purposes, return the certificate associated with that
+ * key. */
 authority_cert_t *
 get_my_v3_legacy_cert(void)
 {
   return legacy_key_certificate;
 }
 
-/* DOCDOC get_my_v3_legacy_signing_key */
+/** If we're an authority, and we're using a legacy authority identity key for
+ * emergency migration purposes, return that key. */
 crypto_pk_env_t *
 get_my_v3_legacy_signing_key(void)
 {
@@ -285,10 +288,14 @@ init_key_from_file(const char *fname, int generate, int severity)
   return NULL;
 }
 
-/* DOCDOC load_authority_keyset */
+/** Try to load the vote-signing private key and certificate for being a v3
+ * directory authority, and make sure they match.  If <b>legacy</b>, load a
+ * legacy key/cert set for emergency key migration; otherwise load the regular
+ * key/cert set.  On success, store them into *<b>key_out</b> and
+ * *<b>cert_out</b> respectively, and return 0.  On failrue, return -1. */
 static int
 load_authority_keyset(int legacy, crypto_pk_env_t **key_out,
-                       authority_cert_t **cert_out)
+                      authority_cert_t **cert_out)
 {
   int r = -1;
   char *fname = NULL, *cert = NULL;
diff --git a/src/or/routerlist.c b/src/or/routerlist.c
index 78c02ddb24..7004d938a8 100644
--- a/src/or/routerlist.c
+++ b/src/or/routerlist.c
@@ -549,7 +549,8 @@ router_should_rebuild_store(desc_store_t *store)
     return store->journal_len > (1<<15);
 }
 
-/* DOCDOC desc_get_store */
+/** Return the desc_store_t in <b>rl</b> that should be used to store
+ * <b>sd</b>. */
 static INLINE desc_store_t *
 desc_get_store(routerlist_t *rl, signed_descriptor_t *sd)
 {
@@ -2466,7 +2467,10 @@ dump_routerlist_mem_usage(int severity)
 #endif
 }
 
-/* DOCDOC _routerlist_find_elt */
+/** Debugging helper: If <b>idx</b> is nonnegative, assert that <b>ri</b> is
+ * in <b>sl</b> at position <b>idx</b>. Otherwise, search <b>sl</b> for
+ * <b>ri</b>.  Return the index of <b>ri</b> in <b>sl</b>, or -1 if <b>ri</b>
+ * is not in <b>sl</b>. */
 static INLINE int
 _routerlist_find_elt(smartlist_t *sl, void *ri, int idx)
 {
diff --git a/src/or/routerparse.c b/src/or/routerparse.c
index aa8457ece7..498866e690 100644
--- a/src/or/routerparse.c
+++ b/src/or/routerparse.c
@@ -2847,7 +2847,11 @@ token_free(directory_token_t *tok)
     goto done_tokenizing;                                          \
   STMT_END
 
-/* DOCDOC token_check_object */
+/** Helper: make sure that the token <b>tok</b> with keyword <b>kwd</b> obeys
+ * the object syntax of <b>o_syn</b>.  Allocate all storage in <b>area</b>.
+ * Return <b>tok</b> on success, or a new _ERR token if the token didn't
+ * conform to the syntax we wanted.
+ **/
 static INLINE directory_token_t *
 token_check_object(memarea_t *area, const char *kwd,
                    directory_token_t *tok, obj_syntax o_syn)
@@ -2855,6 +2859,7 @@ token_check_object(memarea_t *area, const char *kwd,
   char ebuf[128];
   switch (o_syn) {
     case NO_OBJ:
+      /* No object is allowed for this token. */
       if (tok->object_body) {
         tor_snprintf(ebuf, sizeof(ebuf), "Unexpected object for %s", kwd);
         RET_ERR(ebuf);
@@ -2865,20 +2870,21 @@ token_check_object(memarea_t *area, const char *kwd,
       }
       break;
     case NEED_OBJ:
+      /* There must be a (non-key) object. */
       if (!tok->object_body) {
         tor_snprintf(ebuf, sizeof(ebuf), "Missing object for %s", kwd);
         RET_ERR(ebuf);
       }
       break;
-    case NEED_KEY_1024:
-    case NEED_SKEY_1024:
+    case NEED_KEY_1024: /* There must be a 1024-bit public key. */
+    case NEED_SKEY_1024: /* There must be a 1024-bit private key. */
       if (tok->key && crypto_pk_keysize(tok->key) != PK_BYTES) {
         tor_snprintf(ebuf, sizeof(ebuf), "Wrong size on key for %s: %d bits",
                      kwd, (int)crypto_pk_keysize(tok->key));
         RET_ERR(ebuf);
       }
       /* fall through */
-    case NEED_KEY:
+    case NEED_KEY: /* There must be some kind of key. */
       if (!tok->key) {
         tor_snprintf(ebuf, sizeof(ebuf), "Missing public key for %s", kwd);
       }
@@ -2897,6 +2903,7 @@ token_check_object(memarea_t *area, const char *kwd,
       }
       break;
     case OBJ_OK:
+      /* Anything goes with this token. */
       break;
   }
 
diff --git a/src/or/test.c b/src/or/test.c
index e2d4dacca4..f6d529d74e 100644
--- a/src/or/test.c
+++ b/src/or/test.c
@@ -54,7 +54,9 @@ int have_failed = 0;
 
 static char temp_dir[256];
 
-/* DOCDOC setup_directory */
+/** Select and create the temporary directory we'll use to run our unit tests.
+ * Store it in <b>temp_dir</b>.  Exit immediately if we can't create it.
+ * idempotent. */
 static void
 setup_directory(void)
 {
@@ -79,7 +81,7 @@ setup_directory(void)
   is_setup = 1;
 }
 
-/* DOCDOC get_fname */
+/** Return a filename relative to our testing temporary directory */
 static const char *
 get_fname(const char *name)
 {
@@ -89,7 +91,8 @@ get_fname(const char *name)
   return buf;
 }
 
-/* DOCDOC remove_directory */
+/** Remove all files stored under the temporary directory, and the directory
+ * itself. */
 static void
 remove_directory(void)
 {
@@ -113,12 +116,17 @@ remove_directory(void)
 #undef CACHE_GENERATED_KEYS
 
 static crypto_pk_env_t *pregen_keys[5] = {NULL, NULL, NULL, NULL, NULL};
-/* DOCDOC pk_generate */
+#define N_PREGEN_KEYS ((int)(sizeof(pregen_keys)/sizeof(pregen_keys[0])))
+
+/** Generate and return a new keypair for use in unit tests.  If we're using
+ * the key cache optimization, we might reuse keys: we only guarantee that
+ * keys made with distinct values for <b>idx</b> are different.  The value of
+ * <b>idx</b> must be at least 0, and less than N_PREGEN_KEYS. */
 static crypto_pk_env_t *
 pk_generate(int idx)
 {
 #ifdef CACHE_GENERATED_KEYS
-  tor_assert(idx < (int)(sizeof(pregen_keys)/sizeof(pregen_keys[0])));
+  tor_assert(idx < N_PREGEN_KEYS);
   if (! pregen_keys[idx]) {
     pregen_keys[idx] = crypto_new_pk_env();
     tor_assert(!crypto_pk_generate_key(pregen_keys[idx]));
@@ -133,12 +141,12 @@ pk_generate(int idx)
 #endif
 }
 
-/* DOCDOC free_pregenerated_keys */
+/** Free all storage used for the cached key optimization. */
 static void
 free_pregenerated_keys(void)
 {
   unsigned idx;
-  for (idx = 0; idx < sizeof(pregen_keys)/sizeof(pregen_keys[0]); ++idx) {
+  for (idx = 0; idx < N_PREGEN_KEYS; ++idx) {
     if (pregen_keys[idx]) {
       crypto_free_pk_env(pregen_keys[idx]);
       pregen_keys[idx] = NULL;
@@ -146,7 +154,7 @@ free_pregenerated_keys(void)
   }
 }
 
-/* DOCDOC test_buffers */
+/** Run unit tests for buffers.c */
 static void
 test_buffers(void)
 {
@@ -389,7 +397,7 @@ test_buffers(void)
     buf_free(buf2);
 }
 
-/* DOCDOC test_crypto_dh */
+/** Run unit tests for Diffie-Hellman functionality. */
 static void
 test_crypto_dh(void)
 {
@@ -431,7 +439,8 @@ test_crypto_dh(void)
   crypto_dh_free(dh2);
 }
 
-/* DOCDOC test_crypto_rng */
+/** Run unit tests for our random number generation function and its wrappers.
+ */
 static void
 test_crypto_rng(void)
 {
@@ -469,7 +478,7 @@ test_crypto_rng(void)
   ;
 }
 
-/* DOCDOC test_crypto_aes */
+/** Run unit tests for our AES functionality */
 static void
 test_crypto_aes(void)
 {
@@ -599,7 +608,7 @@ test_crypto_aes(void)
   tor_free(data3);
 }
 
-/* DOCDOC test_crypto_sha */
+/** Run unit tests for our SHA-1 functionality */
 static void
 test_crypto_sha(void)
 {
@@ -668,7 +677,7 @@ test_crypto_sha(void)
     crypto_free_digest_env(d2);
 }
 
-/* DOCDOC test_crypto_pk */
+/** Run unit tests for our public key crypto functions */
 static void
 test_crypto_pk(void)
 {
@@ -778,7 +787,7 @@ test_crypto_pk(void)
   tor_free(encoded);
 }
 
-/* DOCDOC test_crypto */
+/** Run unit tests for misc crypto functionality. */
 static void
 test_crypto(void)
 {
@@ -887,7 +896,7 @@ test_crypto(void)
   tor_free(data3);
 }
 
-/* DOCDOC test_crypto_s2k */
+/** Run unit tests for our secret-to-key passphrase hashing functionality. */
 static void
 test_crypto_s2k(void)
 {
@@ -920,7 +929,8 @@ test_crypto_s2k(void)
   tor_free(buf3);
 }
 
-/* DOCDOC _compare_strs */
+/** Helper: return a tristate based on comparing the strings in *<b>a</b> and
+ * *<b>b</b>. */
 static int
 _compare_strs(const void **a, const void **b)
 {
@@ -928,7 +938,8 @@ _compare_strs(const void **a, const void **b)
   return strcmp(s1, s2);
 }
 
-/* DOCDOC _compare_without_first_ch */
+/** Helper: return a tristate based on comparing the strings in *<b>a</b> and
+ * *<b>b</b>, excluding a's first character, and ignoring case. */
 static int
 _compare_without_first_ch(const void *a, const void **b)
 {
@@ -936,7 +947,7 @@ _compare_without_first_ch(const void *a, const void **b)
   return strcasecmp(s1+1, s2);
 }
 
-/* DOCDOC test_util */
+/** Test basic utility functionality. */
 static void
 test_util(void)
 {
@@ -1429,7 +1440,7 @@ _test_eq_ip6(struct in6_addr *a, struct in6_addr *b, const char *e1,
     test_eq(port2, pt2);                                   \
   STMT_END
 
-/* DOCDOC test_util_ip6_helpers */
+/** Run unit tests for IPv6 encoding/decoding/manipulation functions. */
 static void
 test_util_ip6_helpers(void)
 {
@@ -1755,7 +1766,7 @@ test_util_ip6_helpers(void)
   ;
 }
 
-/* DOCDOC test_util_smartlist_basic */
+/** Run unit tests for basic dynamic-sized array functionality. */
 static void
 test_util_smartlist_basic(void)
 {
@@ -1794,7 +1805,7 @@ test_util_smartlist_basic(void)
   smartlist_free(sl);
 }
 
-/* DOCDOC test_util_smartlist_strings */
+/** Run unit tests for smartlist-of-strings functionality. */
 static void
 test_util_smartlist_strings(void)
 {
@@ -2024,7 +2035,7 @@ test_util_smartlist_strings(void)
   tor_free(cp_alloc);
 }
 
-/* DOCDOC test_util_smartlist_overlap */
+/** Run unit tests for smartlist set manipulation functions. */
 static void
 test_util_smartlist_overlap(void)
 {
@@ -2077,7 +2088,7 @@ test_util_smartlist_overlap(void)
   smartlist_free(sl);
 }
 
-/* DOCDOC test_util_smartlist_digests */
+/** Run unit tests for smartlist-of-digests functions. */
 static void
 test_util_smartlist_digests(void)
 {
@@ -2110,7 +2121,7 @@ test_util_smartlist_digests(void)
   smartlist_free(sl);
 }
 
-/* DOCDOC test_util_smartlist_join */
+/** Run unit tests for concatenate-a-smartlist-of-strings functions. */
 static void
 test_util_smartlist_join(void)
 {
@@ -2162,7 +2173,7 @@ test_util_smartlist_join(void)
   tor_free(joined);
 }
 
-/* DOCDOC test_util_bitarray */
+/** Run unit tests for bitarray code */
 static void
 test_util_bitarray(void)
 {
@@ -2204,7 +2215,8 @@ test_util_bitarray(void)
     bitarray_free(ba);
 }
 
-/* DOCDOC test_util_digestset */
+/** Run unit tests for digest set code (implemented as a hashtable or as a
+ * bloom filter) */
 static void
 test_util_digestset(void)
 {
@@ -2253,18 +2265,18 @@ static strmap_t *_thread_test_strmap = NULL;
 static char *_thread1_name = NULL;
 static char *_thread2_name = NULL;
 
-/* DOCDOC _thread_test_func */
 static void _thread_test_func(void* _s) ATTR_NORETURN;
 
 static int t1_count = 0;
 static int t2_count = 0;
 
+/** Helper function for threading unit tests: This function runs in a
+ * subthread. It grabs its own mutex (start1 or start2) to make sure that it
+ * should start, then it repeatedly alters _test_thread_strmap protected by
+ * _thread_test_mutex. */
 static void
 _thread_test_func(void* _s)
 {
-  /* This function runs in a subthread. It grabs its own mutex (start1 or
-   * start2) to make sure that it should start, then it repeatedly alters
-   * _test_thread_strmap protected by _thread_test_mutex. */
   char *s = _s;
   int i, *count;
   tor_mutex_t *m;
@@ -2299,7 +2311,7 @@ _thread_test_func(void* _s)
   spawn_exit();
 }
 
-/* DOCDOC test_util_threads */
+/** Run unit tests for threading logic. */
 static void
 test_util_threads(void)
 {
@@ -2371,14 +2383,14 @@ test_util_threads(void)
     tor_mutex_free(_thread_test_start2);
 }
 
-/* DOCDOC _compare_strings_for_pqueue */
+/** Helper: return a tristate based on comparing two strings. */
 static int
 _compare_strings_for_pqueue(const void *s1, const void *s2)
 {
   return strcmp((const char*)s1, (const char*)s2);
 }
 
-/* DOCDOC test_util_pqueue */
+/** Run unit tests for heap-based priority queue functions. */
 static void
 test_util_pqueue(void)
 {
@@ -2436,7 +2448,7 @@ test_util_pqueue(void)
     smartlist_free(sl);
 }
 
-/* DOCDOC test_util_gzip */
+/** Run unit tests for compression functions */
 static void
 test_util_gzip(void)
 {
@@ -2543,7 +2555,7 @@ test_util_gzip(void)
   tor_free(buf1);
 }
 
-/* DOCDOC test_util_strmap */
+/** Run unit tests for string-to-void* map functions */
 static void
 test_util_strmap(void)
 {
@@ -2634,7 +2646,7 @@ test_util_strmap(void)
   tor_free(visited);
 }
 
-/* DOCDOC test_util_mmap */
+/** Run unit tests for mmap() wrapper functionality. */
 static void
 test_util_mmap(void)
 {
@@ -2711,7 +2723,7 @@ test_util_mmap(void)
     tor_munmap_file(mapping);
 }
 
-/* DOCDOC test_util_control_formats */
+/** Run unit tests for escaping/unescaping data for use by controllers. */
 static void
 test_util_control_formats(void)
 {
@@ -2729,7 +2741,7 @@ test_util_control_formats(void)
   tor_free(out);
 }
 
-/* DOCDOC test_onion_handshake */
+/** Run unit tests for the onion handshake code. */
 static void
 test_onion_handshake(void)
 {
@@ -2778,7 +2790,7 @@ test_onion_handshake(void)
 
 extern smartlist_t *fingerprint_list;
 
-/* DOCDOC test_dir_format */
+/** Run unit tests for router descriptor generation logic. */
 static void
 test_dir_format(void)
 {
@@ -3099,7 +3111,7 @@ test_dir_format(void)
   tor_free(dir2); /* And more !*/
 }
 
-/* DOCDOC test_dirutil */
+/** Run unit tests for misc directory functions. */
 static void
 test_dirutil(void)
 {
@@ -3135,7 +3147,9 @@ extern const char AUTHORITY_SIGNKEY_2[];
 extern const char AUTHORITY_CERT_3[];
 extern const char AUTHORITY_SIGNKEY_3[];
 
-/* DOCDOC test_same_voter */
+/** Helper: Test that two networkstatus_voter_info_t do in fact represent the
+ * same voting authority, and that they do in fact have all the same
+ * information. */
 static void
 test_same_voter(networkstatus_voter_info_t *v1,
                 networkstatus_voter_info_t *v2)
@@ -3152,7 +3166,7 @@ test_same_voter(networkstatus_voter_info_t *v1,
   ;
 }
 
-/* DOCDOC test_util_order_functions */
+/** Run unit tests for getting the median of a list. */
 static void
 test_util_order_functions(void)
 {
@@ -3182,7 +3196,8 @@ test_util_order_functions(void)
   ;
 }
 
-/* DOCDOC generate_ri_from_rs */
+/** Helper: Make a new routerinfo containing the right information for a
+ * given vote_routerstatus_t. */
 static routerinfo_t *
 generate_ri_from_rs(const vote_routerstatus_t *vrs)
 {
@@ -3205,7 +3220,8 @@ generate_ri_from_rs(const vote_routerstatus_t *vrs)
   return r;
 }
 
-/* DOCDOC test_v3_networkstatus */
+/** Run unit tests for generating and parsing V3 consensus networkstatus
+ * documents. */
 static void
 test_v3_networkstatus(void)
 {
@@ -3704,7 +3720,9 @@ test_v3_networkstatus(void)
     ns_detached_signatures_free(dsig2);
 }
 
-/* DOCDOC test_policy_summary_helper */
+/** Helper: Parse the exit policy string in <b>policy_str</b>, and make sure
+ * that policies_summarize() produces the string <b>expected_summary</b> from
+ * it. */
 static void
 test_policy_summary_helper(const char *policy_str,
                            const char *expected_summary)
@@ -3731,7 +3749,7 @@ test_policy_summary_helper(const char *policy_str,
     addr_policy_list_free(policy);
 }
 
-/* DOCDOC test_policies */
+/** Run unit tests for generating summary lines of exit policies */
 static void
 test_policies(void)
 {
@@ -3890,7 +3908,7 @@ test_policies(void)
   }
 }
 
-/* DOCDOC test_rend_fns */
+/** Run unit tests for basic rendezvous functions. */
 static void
 test_rend_fns(void)
 {
@@ -3956,7 +3974,7 @@ test_rend_fns(void)
   tor_free(encoded);
 }
 
-/* DOCDOC bench_aes */
+/** Run AES performance benchmarks. */
 static void
 bench_aes(void)
 {
@@ -3988,7 +4006,7 @@ bench_aes(void)
   crypto_free_cipher_env(c);
 }
 
-/* DOCDOC bench_dmap */
+/** Run digestmap_t performance benchmarks. */
 static void
 bench_dmap(void)
 {
@@ -4052,7 +4070,7 @@ bench_dmap(void)
   smartlist_free(sl2);
 }
 
-/* DOCDOC test_util_mempool */
+/** Run unittests for memory pool allocator */
 static void
 test_util_mempool(void)
 {
@@ -4110,7 +4128,7 @@ test_util_mempool(void)
     mp_pool_destroy(pool);
 }
 
-/* DOCDOC test_util_memarea */
+/** Run unittests for memory area allocator */
 static void
 test_util_memarea(void)
 {
@@ -4206,7 +4224,8 @@ test_util_memarea(void)
   tor_free(malloced_ptr);
 }
 
-/* DOCDOC test_util_datadir */
+/** Run unit tests for utility functions to get file names relative to
+ * the data directory. */
 static void
 test_util_datadir(void)
 {
@@ -4239,8 +4258,7 @@ test_util_datadir(void)
   tor_free(f);
 }
 
-/* Test AES-CTR encryption and decryption with IV. */
-/* DOCDOC test_crypto_aes_iv */
+/** Test AES-CTR encryption and decryption with IV. */
 static void
 test_crypto_aes_iv(void)
 {
@@ -4376,8 +4394,7 @@ test_crypto_aes_iv(void)
     crypto_free_cipher_env(cipher);
 }
 
-/* Test base32 decoding. */
-/* DOCDOC test_crypto_base32_decode */
+/** Test base32 decoding. */
 static void
 test_crypto_base32_decode(void)
 {
@@ -4412,8 +4429,7 @@ test_crypto_base32_decode(void)
   ;
 }
 
-/* Test encoding and parsing of v2 rendezvous service descriptors. */
-/* DOCDOC test_rend_fns_v2 */
+/** Test encoding and parsing of v2 rendezvous service descriptors. */
 static void
 test_rend_fns_v2(void)
 {
@@ -4514,7 +4530,7 @@ test_rend_fns_v2(void)
   tor_free(intro_points_encrypted);
 }
 
-/* DOCDOC test_geoip */
+/** Run unit tests for GeoIP code. */
 static void
 test_geoip(void)
 {
@@ -4580,6 +4596,7 @@ static struct {
   void (*test_fn)(void);
   int is_subent;
   int selected;
+  int is_default;
 } test_array[] = {
   ENT(buffers),
   ENT(crypto),
@@ -4618,11 +4635,12 @@ static struct {
   ENT(rend_fns),
   SUBENT(rend_fns, v2),
   ENT(geoip),
-  { NULL, NULL, 0, 0 },
+  { NULL, NULL, 0, 0, 0 },
 };
 
 static void syntax(void) ATTR_NORETURN;
-/* DOCDOC syntax */
+
+/** Print a syntax usage message, and exit.*/
 static void
 syntax(void)
 {
@@ -4638,7 +4656,8 @@ syntax(void)
   exit(0);
 }
 
-/* DOCDOC main */
+/** Main entry point for unit test code: parse the command line, and run
+ * some unit tests. */
 int
 main(int c, char**v)
 {