Document most undocumented variables.

svn:r17754

16 files changed, 135 insertions, 88 deletions

diff --git a/src/common/util.c b/src/common/util.c
index 84a40a82a6..4a8d762e4f 100644
--- a/src/common/util.c
+++ b/src/common/util.c
@@ -1392,7 +1392,8 @@ ftime_definitely_after(time_t now, time_t when)
    * after when. */
   return (now + ftime_skew - ftime_slop) >= when;
 }
-/** Return true if we think that <b>now</b> is definitely before <b>when</b>. */
+/** Return true if we think that <b>now</b> is definitely before <b>when</b>.
+ */
 int
 ftime_definitely_before(time_t now, time_t when)
 {
diff --git a/src/or/command.c b/src/or/command.c
index baa435695f..7ad20f0098 100644
--- a/src/or/command.c
+++ b/src/or/command.c
@@ -20,19 +20,19 @@ const char command_c_id[] =
 
 #include "or.h"
 
-/** Keep statistics about how many of each type of cell we've received. */
+/** How many CELL_PADDING cells have we received, ever? */
 uint64_t stats_n_padding_cells_processed = 0;
-/* DOCDOC stats_n_create_cells_processed */
+/** How many CELL_CREATE cells have we received, ever? */
 uint64_t stats_n_create_cells_processed = 0;
-/* DOCDOC stats_n_created_cells_processed */
+/** How many CELL_CREATED cells have we received, ever? */
 uint64_t stats_n_created_cells_processed = 0;
-/* DOCDOC stats_n_relay_cells_processed */
+/** How many CELL_RELAY cells have we received, ever? */
 uint64_t stats_n_relay_cells_processed = 0;
-/* DOCDOC stats_n_destroy_cells_processed */
+/** How many CELL_DESTROY cells have we received, ever? */
 uint64_t stats_n_destroy_cells_processed = 0;
-/* DOCDOC stats_n_versions_cells_processed */
+/** How many CELL_VERSIONS cells have we received, ever? */
 uint64_t stats_n_versions_cells_processed = 0;
-/* DOCDOC stats_n_netinfo_cells_processed */
+/** How many CELL_NETINFO cells have we received, ever? */
 uint64_t stats_n_netinfo_cells_processed = 0;
 
 /* These are the main functions for processing cells */
diff --git a/src/or/config.c b/src/or/config.c
index fec77e7808..adb4b1950b 100644
--- a/src/or/config.c
+++ b/src/or/config.c
@@ -54,8 +54,8 @@ typedef struct config_abbrev_t {
  * you can abbreviate <b>tok</b>s as <b>tok</b>". */
 #define PLURAL(tok) { #tok, #tok "s", 0, 0 }
 
-/* A list of command-line abbreviations. */
-/* DOCDOC _option_abbrevs */
+/** A list of abbreviations and aliases to map command-line options, obsolete
+ * option names, or alternative option names, to their current values. */
 static config_abbrev_t _option_abbrevs[] = {
   PLURAL(ExitNode),
   PLURAL(EntryNode),
@@ -92,8 +92,8 @@ static config_abbrev_t _option_abbrevs[] = {
   { "HashedControlPassword", "__HashedControlSessionPassword", 1, 0},
   { NULL, NULL, 0, 0},
 };
-/* A list of state-file abbreviations, for compatibility. */
-/* DOCDOC _state_abbrevs */
+
+/** A list of state-file "abbreviations," for compatibility. */
 static config_abbrev_t _state_abbrevs[] = {
   { "AccountingBytesReadInterval", "AccountingBytesReadInInterval", 0, 0 },
   { "HelperNode", "EntryGuard", 0, 0 },
@@ -346,8 +346,8 @@ static config_var_t _option_vars[] = {
   { NULL, CONFIG_TYPE_OBSOLETE, 0, NULL }
 };
 
-/* Keep defaults synchronous with man page and config value check. */
-/* DOCDOC testing_tor_network_defaults */
+/** Override default values with these if the user sets the TestingTorNetwork
+ * option. */
 static config_var_t testing_tor_network_defaults[] = {
   V(ServerDNSAllowBrokenConfig,  BOOL,  "1"),
   V(DirAllowPrivateAddresses,    BOOL,     "1"),
@@ -372,7 +372,8 @@ static config_var_t testing_tor_network_defaults[] = {
 #define VAR(name,conftype,member,initvalue)                             \
   { name, CONFIG_TYPE_ ## conftype, STRUCT_OFFSET(or_state_t, member),  \
       initvalue }
-/* DOCDOC _state_vars */
+
+/** Array of "state" variables saved to the ~/.tor/state file. */
 static config_var_t _state_vars[] = {
   V(AccountingBytesReadInInterval,    MEMUNIT,  NULL),
   V(AccountingBytesWrittenInInterval, MEMUNIT,  NULL),
@@ -412,7 +413,9 @@ typedef struct config_var_description_t {
   const char *description;
 } config_var_description_t;
 
-/* DOCDOC options_description */
+/** Descriptions of the configuration options, to be displayed by online
+ * option browsers */
+/* XXXX022 did anybody want this? at all? If not, kill it.*/
 static config_var_description_t options_description[] = {
   /* ==== general options */
   { "AvoidDiskWrites", "If non-zero, try to write to disk less frequently than"
@@ -584,7 +587,7 @@ static config_var_description_t options_description[] = {
   { NULL, NULL },
 };
 
-/* DOCDOC state_description */
+/** Online description of state variables. */
 static config_var_description_t state_description[] = {
   { "AccountingBytesReadInInterval",
     "How many bytes have we read in this accounting period?" },
@@ -814,13 +817,12 @@ set_options(or_options_t *new_val, char **msg)
   return 0;
 }
 
-/* DOCDOC tor_svn_revision */
 extern const char tor_svn_revision[]; /* from tor_main.c */
 
-/* DOCDOC _version */
+/** The version of this Tor process, as parsed. */
 static char *_version = NULL;
 
-/** Return the current Tor version, possibly */
+/** Return the current Tor version. */
 const char *
 get_version(void)
 {
@@ -4617,7 +4619,8 @@ struct unit_table_t {
   uint64_t multiplier;
 };
 
-/* DOCDOC memory_units */
+/** Table to map the names of memory units to the number of bytes they
+ * contain. */
 static struct unit_table_t memory_units[] = {
   { "",          1 },
   { "b",         1<< 0 },
@@ -4645,7 +4648,8 @@ static struct unit_table_t memory_units[] = {
   { NULL, 0 },
 };
 
-/* DOCDOC time_units */
+/** Table to map the names of time units to the number of seconds they
+ * contain. */
 static struct unit_table_t time_units[] = {
   { "",         1 },
   { "second",   1 },
diff --git a/src/or/control.c b/src/or/control.c
index e0ebd7d591..73aad0c384 100644
--- a/src/or/control.c
+++ b/src/or/control.c
@@ -54,9 +54,13 @@ const char control_c_id[] =
  * list to find out.
  **/
 typedef uint32_t event_mask_t;
-/* DOCDOC global_event_mask1long */
+
+/** An event mask of all the events that controller with the LONG_NAMES option
+ * set is interested in receiving. */
 static event_mask_t global_event_mask1long = 0;
-/* DOCDOC global_event_mask1short */
+
+/** An event mask of all the events that controller with the SHORT_NAMES option
+ * set is interested in receiving. */
 static event_mask_t global_event_mask1short = 0;
 
 /** True iff we have disabled log messages from being sent to the controller */
@@ -66,7 +70,11 @@ static int disable_log_messages = 0;
  * <b>e</b>. */
 #define EVENT_IS_INTERESTING(e) \
   ((global_event_mask1long|global_event_mask1short) & (1<<(e)))
+/** Macro: true if any control connection with the LONG_NAMES option is
+ * interested in events of type <b>e</b>. */
 #define EVENT_IS_INTERESTING1L(e) (global_event_mask1long & (1<<(e)))
+/** Macro: true if any control connection with the SHORT_NAMES option is
+ * interested in events of type <b>e</b>. */
 #define EVENT_IS_INTERESTING1S(e) (global_event_mask1short & (1<<(e)))
 
 /** If we're using cookie-type authentication, how long should our cookies be?
@@ -76,7 +84,9 @@ static int disable_log_messages = 0;
 /** If true, we've set authentication_cookie to a secret code and
  * stored it to disk. */
 static int authentication_cookie_is_set = 0;
-/* DOCDOC authentication_cookie */
+/** If authentication_cookie_is_set, a secret cookie that we've stored to disk
+ * and which we're using to authenticate controllers.  (If the controller can
+ * read it off disk, it has permission to connect. */
 static char authentication_cookie[AUTHENTICATION_COOKIE_LEN];
 
 /** A sufficiently large size to record the last bootstrap phase string. */
diff --git a/src/or/directory.c b/src/or/directory.c
index 250fd7ee54..b383ad5e89 100644
--- a/src/or/directory.c
+++ b/src/or/directory.c
@@ -3268,19 +3268,19 @@ dir_networkstatus_download_failed(smartlist_t *failed, int status_code)
   });
 }
 
-/* DOCDOC server_dl_schedule */
+/** Schedule for when servers should download things in general. */
 static const int server_dl_schedule[] = {
   0, 0, 0, 60, 60, 60*2, 60*5, 60*15, INT_MAX
 };
-/* DOCDOC client_dl_schedule */
+/** Schedule for when clients should download things in general. */
 static const int client_dl_schedule[] = {
   0, 0, 60, 60*5, 60*10, INT_MAX
 };
-/* DOCDOC server_consensus_dl_schedule */
+/** Schedule for when servers should download consensuses. */
 static const int server_consensus_dl_schedule[] = {
   0, 0, 60, 60*5, 60*10, 60*30, 60*30, 60*30, 60*30, 60*30, 60*60, 60*60*2
 };
-/* DOCDOC client_consensus_dl_schedule */
+/** Schedule for when clients should download consensuses. */
 static const int client_consensus_dl_schedule[] = {
   0, 0, 60, 60*5, 60*10, 60*30, 60*60, 60*60, 60*60, 60*60*3, 60*60*6, 60*60*12
 };
diff --git a/src/or/dirserv.c b/src/or/dirserv.c
index 361f44f2e5..71b837f857 100644
--- a/src/or/dirserv.c
+++ b/src/or/dirserv.c
@@ -30,11 +30,13 @@ const char dirserv_c_id[] =
 
 extern time_t time_of_process_start; /* from main.c */
 
-/** Do we need to regenerate the directory when someone asks for it? */
+/** Do we need to regenerate the v1 directory when someone asks for it? */
 static time_t the_directory_is_dirty = 1;
-/* DOCDOC runningrouters_is_dirty */
+/** Do we need to regenerate the v1 runningrouters document when somebody
+ * asks for it? */
 static time_t runningrouters_is_dirty = 1;
-/* DOCDOC the_v2_networkstatus_is_dirty */
+/** Do we need to regenerate our v2 networkstatus document when somebody asks
+ * for it? */
 static time_t the_v2_networkstatus_is_dirty = 1;
 
 /** Most recently generated encoded signed v1 directory. (v1 auth dirservers
@@ -1224,9 +1226,12 @@ directory_too_idle_to_fetch_descriptors(or_options_t *options, time_t now)
 
 /* Used only by non-v1-auth dirservers: The v1 directory and
  * runningrouters we'll serve when requested. */
-/* DOCDOC cached_directory */
+
+/** The v1 directory we'll serve (as a cache or as an authority) if
+ * requested. */
 static cached_dir_t *cached_directory = NULL;
-/* DOCDOC cached_runningrouters */
+/** The v1 runningrouters document we'll serve (as a cache or as an authority)
+ * if requested. */
 static cached_dir_t cached_runningrouters = { NULL, NULL, 0, 0, 0, -1 };
 
 /** Used for other dirservers' v2 network statuses.  Map from hexdigest to
@@ -1640,7 +1645,7 @@ should_generate_v2_networkstatus(void)
 /* Thresholds for server performance: set by
  * dirserv_compute_performance_thresholds, and used by
  * generate_v2_networkstatus */
-/* XXXX stick these all in a struct. */
+
 /* DOCDOC stable_uptime */
 static uint32_t stable_uptime = 0; /* start at a safe value */
 /* DOCDOC stable_mtbf */
diff --git a/src/or/hibernate.c b/src/or/hibernate.c
index fed92dde85..4195fed654 100644
--- a/src/or/hibernate.c
+++ b/src/or/hibernate.c
@@ -103,13 +103,12 @@ static time_t interval_wakeup_time = 0;
 static uint64_t expected_bandwidth_usage = 0;
 /** What unit are we using for our accounting? */
 static time_unit_t cfg_unit = UNIT_MONTH;
+
 /** How many days,hours,minutes into each unit does our accounting interval
  * start? */
-static int cfg_start_day = 0;
-/* DOCDOC cfg_start_hour */
-static int cfg_start_hour = 0;
-/* DOCDOC cfg_start_min */
-static int cfg_start_min = 0;
+static int cfg_start_day = 0,
+           cfg_start_hour = 0,
+           cfg_start_min = 0;
 
 static void reset_accounting(time_t now);
 static int read_bandwidth_usage(void);
diff --git a/src/or/main.c b/src/or/main.c
index dda0cf257e..c8d76bdae1 100644
--- a/src/or/main.c
+++ b/src/or/main.c
@@ -52,9 +52,9 @@ static int stats_prev_global_read_bucket;
  * (used to determine how many bytes we've written). */
 static int stats_prev_global_write_bucket;
 /* XXX we might want to keep stats about global_relayed_*_bucket too. Or not.*/
-/** How many bytes have we read/written since we started the process? */
+/** How many bytes have we read since we started the process? */
 static uint64_t stats_n_bytes_read = 0;
-/* DOCDOC stats_n_bytes_written */
+/** How many bytes have we written since we started the process? */
 static uint64_t stats_n_bytes_written = 0;
 /** What time did this process start up? */
 time_t time_of_process_start = 0;
@@ -1861,7 +1861,9 @@ tor_init(int argc, char *argv[])
   return 0;
 }
 
-/* DOCDOC lockfile */
+/** A lockfile structure, used to prevent two Tors from messing with the
+ * data directory at once.  If this variable is non-NULL, we're holding
+ * the lockfile. */
 static tor_lockfile_t *lockfile = NULL;
 
 /** Try to grab the lock file described in <b>options</b>, if we do not
diff --git a/src/or/networkstatus.c b/src/or/networkstatus.c
index 7b74dab51f..d7a2520278 100644
--- a/src/or/networkstatus.c
+++ b/src/or/networkstatus.c
@@ -39,11 +39,14 @@ static networkstatus_t *current_consensus = NULL;
 /** A v3 consensus networkstatus that we've received, but which we don't
  * have enough certificates to be happy about. */
 static networkstatus_t *consensus_waiting_for_certs = NULL;
-/* DOCDOC consensus_waiting_for_certs_body */
+/** The encoded version of consensus_waiting_for_certs. */
 static char *consensus_waiting_for_certs_body = NULL;
-/* DOCDOC consensus_waiting_for_certs_set_at */
+/** When did we set the current value of consensus_waiting_for_certs?  If this
+ * is too recent, we shouldn't try to fetch a new consensus for a little while,
+ * to give ourselves time to get certificates for this one. */
 static time_t consensus_waiting_for_certs_set_at = 0;
-/* DOCDOC consensus_waiting_for_certs_dl_failed */
+/** Set to 1 if we've been holding on to consensus_waiting_for_certs so long
+ * that we should treat it as maybe being bad. */
 static int consensus_waiting_for_certs_dl_failed = 0;
 
 /** The last time we tried to download a networkstatus, or 0 for "never".  We
diff --git a/src/or/or.h b/src/or/or.h
index ff578b0b4b..1082a79c6a 100644
--- a/src/or/or.h
+++ b/src/or/or.h
@@ -2527,11 +2527,17 @@ typedef struct {
    * count of how many client addresses have contacted us so that we can help
    * the bridge authority guess which countries have blocked access to us. */
   int BridgeRecordUsageByCountry;
+
 #ifdef ENABLE_GEOIP_STATS
-  /* DOCDOC all of these. */
+  /** If true, and Tor is built with GEOIP_STATS support, and we're a
+   * directory, record how many directory requests we get from each country. */
   int DirRecordUsageByCountry;
+  /** Round all GeoIP results to the next multiple of this value, to avoid
+   * leaking information. */
   int DirRecordUsageGranularity;
+  /** Time interval: purge geoip stats after this long. */
   int DirRecordUsageRetainIPs;
+  /** Time interval: Flush geoip data to disk this often. */
   int DirRecordUsageSaveInterval;
 #endif
 
diff --git a/src/or/relay.c b/src/or/relay.c
index 12ec2648d2..75bbf4cd23 100644
--- a/src/or/relay.c
+++ b/src/or/relay.c
@@ -1163,13 +1163,17 @@ connection_edge_process_relay_cell(cell_t *cell, circuit_t *circ,
   return 0; /* for forward compatibility, don't kill the circuit */
 }
 
-/* DOCDOC stats_n_data_cells_packaged */
+/** How many relay_data cells have we built, ever? */
 uint64_t stats_n_data_cells_packaged = 0;
-/* DOCDOC stats_n_data_bytes_packaged */
+/** How many bytes of data have we put in relay_data cells have we built,
+ * ever? This would be RELAY_PAYLOAD_SIZE*stats_n_data_cells_packaged if
+ * every relay cell we ever sent were completely full of data. */
 uint64_t stats_n_data_bytes_packaged = 0;
-/* DOCDOC stats_n_data_cells_received */
+/** How many relay_data cells have we received, ever? */
 uint64_t stats_n_data_cells_received = 0;
-/* DOCDOC stats_n_data_bytes_received */
+/** How many bytes of data have we received relay_data cells, ever? This would
+ * be RELAY_PAYLOAD_SIZE*stats_n_data_cells_packaged if every relay cell we
+ * ever received were completely full of data. */
 uint64_t stats_n_data_bytes_received = 0;
 
 /** While conn->inbuf has an entire relay payload of bytes on it,
@@ -1430,7 +1434,7 @@ circuit_consider_sending_sendme(circuit_t *circ, crypt_path_t *layer_hint)
 /** The total number of cells we have allocated from the memory pool. */
 static int total_cells_allocated = 0;
 
-/* DOCDOC cell_pool */
+/** A memory pool to allocate packed_cell_t objects. */
 static mp_pool_t *cell_pool = NULL;
 
 /** Allocate structures to hold cells. */
diff --git a/src/or/router.c b/src/or/router.c
index 79c5be65b5..ec36bdfe91 100644
--- a/src/or/router.c
+++ b/src/or/router.c
@@ -45,9 +45,11 @@ static crypto_pk_env_t *authority_signing_key = NULL;
  * authorities. */
 static authority_cert_t *authority_key_certificate = NULL;
 
-/* DOCDOC legacy_signing_key */
+/** For emergency V3 authority key migration: An extra signing key that we use
+ * with our old (obsolete) identity key for a while. */
 static crypto_pk_env_t *legacy_signing_key = NULL;
-/* DOCDOC legacy_key_certificate */
+/** For emergency V3 authority key migration: An extra certificate to
+ * authenticate legacy_signing_key with our obsolete identity key.*/
 static authority_cert_t *legacy_key_certificate = NULL;
 
 /* (Note that v3 authorities also have a separate "authority identity key",
@@ -1606,8 +1608,7 @@ router_guess_address_from_dir_headers(uint32_t *guess)
   return -1;
 }
 
-/* DOCDOC tor_svn_revision */
-extern const char tor_svn_revision[]; /* from main.c */
+extern const char tor_svn_revision[]; /* from tor_main.c */
 
 /** Set <b>platform</b> (max length <b>len</b>) to a NUL-terminated short
  * string describing the version of Tor and the operating system we're
diff --git a/src/or/routerparse.c b/src/or/routerparse.c
index 46eaceadb8..3497ffbeef 100644
--- a/src/or/routerparse.c
+++ b/src/or/routerparse.c
@@ -321,6 +321,7 @@ static token_rule_t dir_token_table[] = {
   END_OF_TABLE
 };
 
+/** List of tokens common to V3 authority certificates and V3 consensuses. */
 #define CERTIFICATE_MEMBERS                                                  \
   T1("dir-key-certificate-version", K_DIR_KEY_CERTIFICATE_VERSION,           \
                                                      GE(1),       NO_OBJ ),  \
@@ -333,7 +334,7 @@ static token_rule_t dir_token_table[] = {
                                                      NO_ARGS,     NEED_OBJ), \
   T01("dir-address",     K_DIR_ADDRESS,              GE(1),       NO_OBJ),
 
-/* DOCDOC dir_key_certificate_table */
+/** List of tokens allowable in V3 authority certificates. */
 static token_rule_t dir_key_certificate_table[] = {
   CERTIFICATE_MEMBERS
   T1("fingerprint",      K_FINGERPRINT,              CONCAT_ARGS, NO_OBJ ),
@@ -374,7 +375,7 @@ static token_rule_t client_keys_token_table[] = {
   END_OF_TABLE
 };
 
-/* DOCDOC networkstatus_token_table */
+/** List of tokens allowed in V3 networkstatus votes. */
 static token_rule_t networkstatus_token_table[] = {
   T1("network-status-version", K_NETWORK_STATUS_VERSION,
                                                    GE(1),       NO_OBJ ),
@@ -400,7 +401,8 @@ static token_rule_t networkstatus_token_table[] = {
 
   END_OF_TABLE
 };
-/* DOCDOC networkstatus_consensus_token_table */
+
+/** List of tokens allowed in V3 networkstatus consensuses. */
 static token_rule_t networkstatus_consensus_token_table[] = {
   T1("network-status-version", K_NETWORK_STATUS_VERSION,
                                                    GE(1),       NO_OBJ ),
@@ -432,7 +434,7 @@ static token_rule_t networkstatus_vote_footer_token_table[] = {
   END_OF_TABLE
 };
 
-/* DOCDOC networkstatus_detached_signature_token_table */
+/** List of tokens allowable 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 ),
   T1("valid-after",            K_VALID_AFTER,      CONCAT_ARGS, NO_OBJ ),
diff --git a/src/or/test.c b/src/or/test.c
index 521d557a2e..a75d074163 100644
--- a/src/or/test.c
+++ b/src/or/test.c
@@ -6,7 +6,8 @@
 const char test_c_id[] =
   "$Id$";
 
-/* DOCDOC tor_svn_revision */
+/* Ordinarily defined in tor_main.c; this bit is just here to provide one
+ * since we're not linking to tor_main.c */
 const char tor_svn_revision[] = "";
 
 /**
@@ -2261,27 +2262,23 @@ test_util_digestset(void)
   smartlist_free(included);
 }
 
-/* stop threads running at once. */
-/* DOCDOC _thread_test_mutex */
+/** mutex for thread test to stop the threads hitting data at the same time. */
 static tor_mutex_t *_thread_test_mutex = NULL;
-/* make sure that threads have to run at the same time. */
-/* DOCDOC _thread_test_start1 */
-static tor_mutex_t *_thread_test_start1 = NULL;
-/* DOCDOC _thread_test_start2 */
-static tor_mutex_t *_thread_test_start2 = NULL;
-/* DOCDOC _thread_test_strmap */
+/** mutexes for the thread test to make sure that the threads have to
+ * interleave somewhat. */
+static tor_mutex_t *_thread_test_start1 = NULL,
+                   *_thread_test_start2 = NULL;
+/** Shared strmap for the thread test. */
 static strmap_t *_thread_test_strmap = NULL;
-/* DOCDOC _thread1_name */
+/** The name of thread1 for the thread test */
 static char *_thread1_name = NULL;
-/* DOCDOC _thread2_name */
+/** The name of thread2 for the thread test */
 static char *_thread2_name = NULL;
 
 static void _thread_test_func(void* _s) ATTR_NORETURN;
 
-/* DOCDOC t1_count */
-static int t1_count = 0;
-/* DOCDOC t2_count */
-static int t2_count = 0;
+/** How many iterations have the threads in the unit test run? */
+static int t1_count = 0, 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
@@ -3154,17 +3151,11 @@ test_dirutil(void)
   smartlist_free(sl);
 }
 
-/* DOCDOC AUTHORITY_CERT_1 */
 extern const char AUTHORITY_CERT_1[];
-/* DOCDOC AUTHORITY_SIGNKEY_1 */
 extern const char AUTHORITY_SIGNKEY_1[];
-/* DOCDOC AUTHORITY_CERT_2 */
 extern const char AUTHORITY_CERT_2[];
-/* DOCDOC AUTHORITY_SIGNKEY_2 */
 extern const char AUTHORITY_SIGNKEY_2[];
-/* DOCDOC AUTHORITY_CERT_3 */
 extern const char AUTHORITY_CERT_3[];
-/* DOCDOC AUTHORITY_SIGNKEY_3 */
 extern const char AUTHORITY_SIGNKEY_3[];
 
 /** Helper: Test that two networkstatus_voter_info_t do in fact represent the
@@ -4608,17 +4599,27 @@ test_geoip(void)
   tor_free(s);
 }
 
+/** For test_array. Declare an CLI-invocable off-by-default function in the
+ * unit tests, with function name and user-visible name <b>x</b>*/
 #define DISABLED(x) { #x, x, 0, 0, 0 }
+/** For test_array. Declare an CLI-invocable unit test function, with function
+ * name test_<b>x</b>(), and user-visible name <b>x</b> */
 #define ENT(x) { #x, test_ ## x, 0, 0, 1 }
+/** For test_array. Declare an CLI-invocable unit test function, with function
+ * name test_<b>x</b>_<b>y</b>(), and user-visible name
+ * <b>x</b>/<b>y</b>. This function will be treated as a subentry of <b>x</b>,
+ * so that invoking <b>x</b> from the CLI invokes this test too. */
 #define SUBENT(x,y) { #x "/" #y, test_ ## x ## _ ## y, 1, 0, 1 }
 
+/** An array of functions and information for all the unit tests we can run. */
 static struct {
-  const char *test_name;
-  void (*test_fn)(void);
-  int is_subent;
-  int selected;
-  int is_default;
-/* DOCDOC test_array */
+  const char *test_name; /**< How does the user refer to this test from the
+                          * command line? */
+  void (*test_fn)(void); /**< What function is called to run this test? */
+  int is_subent; /**< Is this a subentry of a bigger set of related tests? */
+  int selected; /**< Are we planning to run this one? */
+  int is_default; /**< If the user doesn't say what tests they want, do they
+                   * get this function by default? */
 } test_array[] = {
   ENT(buffers),
   ENT(crypto),
diff --git a/src/or/test_data.c b/src/or/test_data.c
index 7abd197a6c..cb8958a664 100644
--- a/src/or/test_data.c
+++ b/src/or/test_data.c
@@ -6,6 +6,7 @@
 const char test_data_c_id[] =
   "$Id: /tor/trunk/src/or/test.c 13338 2007-06-10T19:13:32.101740Z nickm  $";
 
+/** First of 3 example authority certificates for unit testing. */
 const char AUTHORITY_CERT_1[] =
 "dir-key-certificate-version 3\n"
 "fingerprint D867ACF56A9D229B35C25F0090BC9867E906BE69\n"
@@ -47,6 +48,7 @@ const char AUTHORITY_CERT_1[] =
 "eCHd0K8NrQK0ipVk/7zcPDKOPeo9Y5aj/f6X/pDHtb+Dd5sT+l82G/Tqy4DIYUYR\n"
 "-----END SIGNATURE-----\n";
 
+/** The private signing key for AUTHORITY_CERT_1 */
 const char AUTHORITY_SIGNKEY_1[] =
 "-----BEGIN RSA PRIVATE KEY-----\n"
 "MIICWwIBAAKBgQCz0lCJ8rhLujVdzY6M6ZWp4iBAc0FxI79cff/pqp8GQAaWFZrs\n"
@@ -64,6 +66,7 @@ const char AUTHORITY_SIGNKEY_1[] =
 "Yx4lqK0ca5IkTp3HevwnlWaJgbaOTUspCVshzJBhDA==\n"
 "-----END RSA PRIVATE KEY-----\n";
 
+/** Second of 3 example authority certificates for unit testing. */
 const char AUTHORITY_CERT_2[] =
 "dir-key-certificate-version 3\n"
 "fingerprint 4D44AE0470B9E88FD4558EFEC82698FB33715400\n"
@@ -99,6 +102,7 @@ const char AUTHORITY_CERT_2[] =
 "a8qDHR0tPS9/VkqTPcvUWCZeY3UiDeWPjoK1nea1pz6DHDWglKPx86a0amjjayZQ\n"
 "-----END SIGNATURE-----\n";
 
+/** The private signing key for AUTHORITY_CERT_2 */
 const char AUTHORITY_SIGNKEY_2[] =
 "-----BEGIN RSA PRIVATE KEY-----\n"
 "MIICXgIBAAKBgQDrt3YK0LYd4qr4v1M38sGgDcNGwVLjDgYZzAXoixHES53iR1CZ\n"
@@ -116,6 +120,7 @@ const char AUTHORITY_SIGNKEY_2[] =
 "rjZyXmEZS3oe7TRCDD28GAGMmxSDvNfOOpyn14ishEs5AQ==\n"
 "-----END RSA PRIVATE KEY-----\n";
 
+/** Third of 3 example authority certificates for unit testing. */
 const char AUTHORITY_CERT_3[] =
 "dir-key-certificate-version 3\n"
 "fingerprint ED3719BF554DE9D7D59F5CA5A4F5AD121D020ED9\n"
@@ -151,6 +156,7 @@ const char AUTHORITY_CERT_3[] =
 "pMc65FviIrc/Q5TUku6NNbCbnGll1599PvWuUzkG42lJ17V6psKHIsqGtVdHlCUc\n"
 "-----END SIGNATURE-----\n";
 
+/** The private signing key for AUTHORITY_CERT_3 */
 const char AUTHORITY_SIGNKEY_3[] =
 "-----BEGIN RSA PRIVATE KEY-----\n"
 "MIICXgIBAAKBgQDa0mZVKt/AaM94rlDsnWEyVee6026tW8/NORT9kBtmftm8KYCi\n"
diff --git a/src/or/tor_main.c b/src/or/tor_main.c
index d4eee4291a..4f06f3fa90 100644
--- a/src/or/tor_main.c
+++ b/src/or/tor_main.c
@@ -6,7 +6,10 @@
 const char tor_main_c_id[] =
   "$Id$";
 
-/* DOCDOC tor_svn_revision */
+/** String describing which Tor subversion repository version the source was
+ * built from.  This string is generated by a bit of shell kludging int
+ * src/or/Makefile.am, and is usually right.
+ */
 const char tor_svn_revision[] =
 #ifndef _MSC_VER
 #include "micro-revision.i"