r15530@catbus: nickm | 2007-10-04 12:16:27 -0400

 Add a bunch of function documentation; clean up a little code; fix some XXXXs; tag the nonsensical EXTRAINFO_PURPOSE_GENERAL as nonsesnse; note another bit of "do not cache special routers" code to nuke.


svn:r11761

15 files changed, 255 insertions, 100 deletions

diff --git a/doc/TODO b/doc/TODO
index 0be859b7a..12d1aaaca 100644
--- a/doc/TODO
+++ b/doc/TODO
@@ -52,18 +52,19 @@ Things we'd like to do in 0.2.0.x:
     . 101: Voting on the Tor Directory System (plus 103)
       . Finalize proposal
         * Describe schedule in copious detail.
-      - Get authorities voting
+      . Get authorities voting
         o Code to manage key certificates
           o Download as needed.
             o Code to download
-            . Code to retry download.
+            D Code to retry download.
         o Code to generate consensus from a list of votes
           o Detect whether votes are really all for the same period.
         o Push/pull documents as appropriate.
           o Pull votes and signatures if we don't get them.
-        - Cache votes and signatures on disk?
+        o Cache votes and signatures on disk?
           o Code to keep consensus docs in limbo if they don't have
             have enough signatures.
+          D Save votes on disk.
         o Have clients know which authorities are v3 authorities, and what
           their keys are.
           - While we're at it, let v3 authorities have fqdns lines.
diff --git a/src/common/aes.c b/src/common/aes.c
index 741e11eec..0a6644ed9 100644
--- a/src/common/aes.c
+++ b/src/common/aes.c
@@ -311,7 +311,8 @@ aes_crypt(aes_cnt_cipher_t *cipher, const char *input, size_t len,
   }
 }
 
-/** DOCDOC */
+/** Reset the 128-bit counter of <b>cipher</b> to the 16-bit big-endian value
+ * in <b>iv</b>. */
 void
 aes_set_iv(aes_cnt_cipher_t *cipher, const char *iv)
 {
diff --git a/src/common/util.c b/src/common/util.c
index 1b3f80a12..701256a9a 100644
--- a/src/common/util.c
+++ b/src/common/util.c
@@ -1516,16 +1516,32 @@ write_str_to_file(const char *fname, const char *str, int bin)
   return write_bytes_to_file(fname, str, strlen(str), bin);
 }
 
-/** DOCDOC */
+/** Represents a file that we're writing to, with support for atomic commit:
+ * we can write into a a temporary file, and either remove the file on
+ * failure, or replace the original file on success. */
 struct open_file_t {
-  char *tempname;
-  char *filename;
-  int rename_on_close;
-  int fd;
-  FILE *stdio_file;
+  char *tempname; /**< Name of the temporary file. */
+  char *filename; /**< Name of the original file. */
+  int rename_on_close; /**< Are we using the temporary file or not? */
+  int fd; /**< fd for the open file. */
+  FILE *stdio_file; /**< stdio wrapper for <b>fd</b>. */
 };
 
-/** DOCDOC */
+/** Try to start writing to the file in <b>fname</b>, passing the flags
+ * <b>open_flags</b> to the open() syscall, creating the file (if needed) with
+ * access value <b>mode</b>.  If the O_APPEND flag is set, we append to the
+ * original file.  Otherwise, we open a new a temporary file in the same
+ * directory, and either replace the original or remove the temprorary file
+ * when we're done.
+ *
+ * Return the fd for the newly opened file, and store working data in
+ * *<b>data_out</b>.  The caller should not close the fd manually:
+ * instead, call finish_writing_to_file() or abort_writing_to_file().
+ * Returns -1 on failure.
+ *
+ * NOTE: When not appending, the flags O_CREAT and O_TRUNC are treated
+ * as true and the flag O_EXCL is treated as false.
+ */
 int
 start_writing_to_file(const char *fname, int open_flags, int mode,
                       open_file_t **data_out)
@@ -1551,6 +1567,9 @@ start_writing_to_file(const char *fname, int open_flags, int mode,
       log(LOG_WARN, LD_GENERAL, "Failed to generate filename");
       goto err;
     }
+    /* We always replace an existing temporary file if there is one. */
+    open_flags |= O_CREAT|O_TRUNC;
+    open_flags &= ~O_EXCL;
     new_file->rename_on_close = 1;
   }
 
@@ -1572,7 +1591,9 @@ start_writing_to_file(const char *fname, int open_flags, int mode,
   return -1;
 }
 
-/** DOCDOC */
+/** Given <b>file_data</b> from start_writing_to_file(), return a stdio FILE*
+ * that can be used to write to the same file.  The caller should not mix
+ * stdio calls with non-stdio calls. */
 FILE *
 fdopen_file(open_file_t *file_data)
 {
@@ -1587,7 +1608,8 @@ fdopen_file(open_file_t *file_data)
   return file_data->stdio_file;
 }
 
-/** DOCDOC */
+/** Combines start_writing_to_file with fdopen_file(): arguments are as
+ * for start_writing_to_file, but  */
 FILE *
 start_writing_to_stdio_file(const char *fname, int open_flags, int mode,
                             open_file_t **data_out)
@@ -1600,7 +1622,10 @@ start_writing_to_stdio_file(const char *fname, int open_flags, int mode,
   return res;
 }
 
-/** DOCDOC */
+/** Helper function: close and free the underlying file and memory in
+ * <b>file_data</b>.  If we were writing into a temporary file, then delete
+ * that file (if abort_write is true) or replaces the target file with
+ * the temporary file (if abort_write is false). */
 static int
 finish_writing_to_file_impl(open_file_t *file_data, int abort_write)
 {
@@ -1641,14 +1666,17 @@ finish_writing_to_file_impl(open_file_t *file_data, int abort_write)
   return r;
 }
 
-/** DOCDOC */
+/** Finish writing to <b>file_data</b>: close the file handle, free memory as
+ * needed, and if using a temporary file, replace the original file with
+ * the temporary file. */
 int
 finish_writing_to_file(open_file_t *file_data)
 {
   return finish_writing_to_file_impl(file_data, 0);
 }
 
-/** DOCDOC */
+/** Finish writing to <b>file_data</b>: close the file handle, free memory as
+ * needed, and if using a temporary file, delete it. */
 int
 abort_writing_to_file(open_file_t *file_data)
 {
diff --git a/src/or/circuitbuild.c b/src/or/circuitbuild.c
index 32077a452..09ff1ccc2 100644
--- a/src/or/circuitbuild.c
+++ b/src/or/circuitbuild.c
@@ -2103,7 +2103,9 @@ entry_guard_free(entry_guard_t *e)
   tor_free(e);
 }
 
-/** DOCDOC */
+/** Remove any entry guard which was selected by an unknown version of Tor,
+ * or which was selected by a version of Tor that's known to select
+ * entry guards badly. */
 static int
 remove_obsolete_entry_guards(void)
 {
@@ -2512,7 +2514,7 @@ choose_random_entry(cpath_build_state_t *state)
   return r;
 }
 
-/** DOCDOC */
+/** Helper: Return the start of the month containing <b>time</b>. */
 static time_t
 start_of_month(time_t now)
 {
diff --git a/src/or/control.c b/src/or/control.c
index aa4d6af77..fa2ba855b 100644
--- a/src/or/control.c
+++ b/src/or/control.c
@@ -1249,7 +1249,15 @@ getinfo_helper_misc(control_connection_t *conn, const char *question,
   return 0;
 }
 
-/** DOCDOC */
+/** Awful hack: return a newly allocated string based on a routerinfo and
+ * (possibly) an extrainfo, sticking the read-history and write-history from
+ * <b>ei</b> into the resulting string.  The thing you get back won't
+ * necessarily have a valid signature.
+ *
+ * New code should never use this; it's for backward compatibiliy.
+ *
+ * NOTE: <b>ri_body</b> is as returned by signed_descriptor_get_body: it might
+ * not be NUL-terminated. */
 static char *
 munge_extrainfo_into_routerinfo(const char *ri_body, signed_descriptor_t *ri,
                                 signed_descriptor_t *ei)
@@ -2355,7 +2363,8 @@ handle_control_closecircuit(control_connection_t *conn, uint32_t len,
   return 0;
 }
 
-/** DOCDOC */
+/** Called when we get a RESOLVE command: start trying to resolve
+ * the listed addresses. */
 static int
 handle_control_resolve(control_connection_t *conn, uint32_t len,
                        const char *body)
@@ -2390,7 +2399,7 @@ handle_control_resolve(control_connection_t *conn, uint32_t len,
   return 0;
 }
 
-/** DOCDOC */
+/** Called when we get a PROTOCOLINFO command: send back a reply. */
 static int
 handle_control_protocolinfo(control_connection_t *conn, uint32_t len,
                             const char *body)
@@ -3554,7 +3563,8 @@ control_event_guard(const char *nickname, const char *digest,
   return 0;
 }
 
-/** DOCDOC */
+/** Helper: Return a newly allocated string containing a path to the
+ * file where we store our authentication cookie. */
 static char *
 get_cookie_file(void)
 {
diff --git a/src/or/directory.c b/src/or/directory.c
index da565b2ff..c9fe224bc 100644
--- a/src/or/directory.c
+++ b/src/or/directory.c
@@ -1066,7 +1066,12 @@ body_is_plausible(const char *body, size_t len, int purpose)
   }
 }
 
-/** DOCDOC */
+/** Called when we've just fetched a bunch of router descriptors in
+ * <b>body</b>.  The list <b>which</b>, if present, holds digests for
+ * descriptors we requested: descriptor digests if <b>descriptor_digests</b>
+ * is true, or identity digests otherwise.  Parse the descriptors, validate
+ * them, and annotate them as having purpose <b>purpose</b> and as having been
+ * downloaded from <b>source</b>. */
 static void
 load_downloaded_routers(const char *body, smartlist_t *which,
                         int descriptor_digests,
@@ -1077,6 +1082,7 @@ load_downloaded_routers(const char *body, smartlist_t *which,
   char time_buf[ISO_TIME_LEN+1];
   int general = router_purpose == ROUTER_PURPOSE_GENERAL;
   format_iso_time(time_buf, time(NULL));
+  tor_assert(source);
 
   if (tor_snprintf(buf, sizeof(buf),
                    "@downloaded-at %s\n"
diff --git a/src/or/dirserv.c b/src/or/dirserv.c
index 9ad888d2a..b2ec0c3cf 100644
--- a/src/or/dirserv.c
+++ b/src/or/dirserv.c
@@ -1694,10 +1694,11 @@ version_from_platform(const char *platform)
 
 /** Helper: write the router-status information in <b>rs</b> into <b>buf</b>,
  * which has at least <b>buf_len</b> free characters.  Do NUL-termination.
- * Use the same format as in network-status documents.  If <b>platform</b> is
+ * Use the same format as in network-status documents.  If <b>version</b> is
  * non-NULL, add a "v" line for the platform.  Return 0 on success, -1 on
- * failure.
- * DOCDOC new arguments */
+ * failure.  If <b>first_line_only<b> is true, don't include any flags
+ * or version line.
+ */
 int
 routerstatus_format_entry(char *buf, size_t buf_len,
                           routerstatus_t *rs, const char *version,
@@ -1918,6 +1919,7 @@ set_routerstatus_from_routerinfo(routerstatus_t *rs,
 
 /** Return a new networkstatus_vote_t* containing our current opinion. (For v3
  * authorities */
+/* XXXX020 possibly rename and relocate to dirvote.c? */
 static networkstatus_vote_t *
 generate_networkstatus_vote_obj(crypto_pk_env_t *private_key,
                                 authority_cert_t *cert)
@@ -2238,7 +2240,8 @@ format_networkstatus_vote(crypto_pk_env_t *private_signing_key,
   return status;
 }
 
-/** DOCDOC */
+/** Replace the value of <b>the_v3_networkstatus_vote</b> with a
+ * new vote, and return that value.  Returns NULL on failure. */
 /* XXXX020 possibly rename and relocate to dirvote.c? */
 cached_dir_t *
 generate_v3_networkstatus(void)
diff --git a/src/or/dirvote.c b/src/or/dirvote.c
index b3f042cd8..1609c1b61 100644
--- a/src/or/dirvote.c
+++ b/src/or/dirvote.c
@@ -1048,25 +1048,26 @@ dirvote_get_start_of_next_interval(time_t now, int interval)
 static struct {
   /** When do we generate and distribute our vote for this interval? */
   time_t voting_starts;
-  /** DOCDOC */
+  /** When do we send an HTTP request for any votes that we haven't
+   * been posted yet?*/
   time_t fetch_missing_votes;
   /** When do we give up on getting more votes and generate a consensus? */
   time_t voting_ends;
-  /** DOCDOC */
+  /** When do we send an HTTP request for any signatures we're expecting to
+   * see on the consensus? */
   time_t fetch_missing_signatures;
   /** When do we publish the consensus? */
   time_t interval_starts;
-
   /** When do we discard old votes and pending detached signatures? */
   time_t discard_old_votes;
 
   /* True iff we have generated and distributed our vote. */
   int have_voted;
-  /* DOCDOC */
+  /* True iff we've requested missing votes. */
   int have_fetched_missing_votes;
   /* True iff we have built a consensus and sent the signatures around. */
   int have_built_consensus;
-  /* DOCDOC */
+  /* True iff we've fetched missing signatures. */
   int have_fetched_missing_signatures;
   /* True iff we have published our consensus. */
   int have_published_consensus;
@@ -1220,7 +1221,9 @@ dirvote_perform_vote(void)
   log_notice(LD_DIR, "Vote posted.");
 }
 
-/** DOCDOC */
+/** Send an HTTP request to every other v3 authority, for the votes of every
+ * authority for which we haven't received a vote yet in this period. (V3
+ * authority only) */
 static void
 dirvote_fetch_missing_votes(void)
 {
@@ -1254,7 +1257,8 @@ dirvote_fetch_missing_votes(void)
   smartlist_free(missing_fps);
 }
 
-/** DOCDOC */
+/** Send a request to every other authority for its detached signatures,
+ * unless we have signatures from all other v3 authorities already. */
 static void
 dirvote_fetch_missing_signatures(void)
 {
@@ -1722,10 +1726,14 @@ dirvote_get_pending_detached_signatures(void)
   return pending_consensus_signatures;
 }
 
-/** Return the vote for the authority with the v3 authority identity key
- * digest <b>id</b>.  If <b>id</b> is NULL, return our own vote. May return
- * NULL if we have no vote for the authority in question.
- * DOCDOC args */
+/** Return a given vote specified by <b>fp</b>.  If <b>by_id</b>, return the
+ * vote for the authority with the v3 authority identity key digest <b>fp</b>;
+ * if <b>by_id</b> is false, return the vote whose digest is <b>fp</b>.  If
+ * <b>fp</b> is NULL, return our own vote.  If <b>include_previous</b> is
+ * false, do not consider any votes for a consensus that's already been built.
+ * If <b>include_pending</b> is false, do not consider any votes for the
+ * consensus that's in progress.  May return NULL if we have no vote for the
+ * authority in question. */
 const cached_dir_t *
 dirvote_get_vote(const char *fp, int by_id, int include_previous,
                  int include_pending)
diff --git a/src/or/main.c b/src/or/main.c
index aec50fbea..49a7245ab 100644
--- a/src/or/main.c
+++ b/src/or/main.c
@@ -908,7 +908,9 @@ run_scheduled_events(time_t now)
     dirserv_test_reachability(now, 0);
   }
 
-  /** 1d. DOCDOC */
+  /** 1d. Periodically, we discount older stability information so that new
+   * stability info counts more, and save the stability information to disk as
+   * appropriate. */
   if (time_to_downrate_stability < now)
     time_to_downrate_stability = rep_hist_downrate_old_runs(now);
   if (authdir_mode_tests_reachability(options)) {
@@ -923,7 +925,8 @@ run_scheduled_events(time_t now)
     }
   }
 
-  /* 1e. DOCDOC */
+  /* 1e. Periodicaly, if we're a v3 authority, we check whether our cert is
+   * close to expiring and warn the admin if it is. */
   if (time_to_check_v3_certificate < now) {
     v3_authority_check_key_expiry();
     time_to_check_v3_certificate = now + CHECK_V3_CERTIFICATE_INTERVAL;
diff --git a/src/or/ntmain.c b/src/or/ntmain.c
index e460582e1..8e88b052b 100644
--- a/src/or/ntmain.c
+++ b/src/or/ntmain.c
@@ -194,7 +194,7 @@ nt_service_is_stopping(void)
   return 0;
 }
 
-/** DOCDOC */
+/** Set the dwCurrentState field for our service to <b>state</b>. */
 void
 nt_service_set_state(DWORD state)
 {
diff --git a/src/or/or.h b/src/or/or.h
index 850073a99..ec5fbec18 100644
--- a/src/or/or.h
+++ b/src/or/or.h
@@ -1167,7 +1167,8 @@ typedef struct {
 #define ROUTER_PURPOSE_CONTROLLER 1
 /** Tor should use this router only for bridge positions in circuits. */
 #define ROUTER_PURPOSE_BRIDGE 2
-/** DOCDOC */
+/** Tor should not use this router; it was marked in cached-descriptors with
+ * a purpose we didn't recognize. */
 #define ROUTER_PURPOSE_UNKNOWN 255
 
   uint8_t purpose; /** What positions in a circuit is this router good for? */
@@ -1187,8 +1188,11 @@ typedef struct {
   int routerlist_index;
 } routerinfo_t;
 
-/** DOCDOC */
-#define EXTRAINFO_PURPOSE_GENERAL -1
+/** DOCDOC
+ * XXXX020 remove this; purpose should have the same value for router
+ * and extrainfo.
+ */
+#define EXTRAINFO_PURPOSE_GENERAL 0
 
 /** Information needed to keep and cache a signed extra-info document. */
 typedef struct extrainfo_t {
@@ -1312,58 +1316,81 @@ typedef struct networkstatus_t {
                          * sorted by identity_digest. */
 } networkstatus_t;
 
-/** DOCDOC */
+/** The claim about a single router, make in a vote. */
 typedef struct vote_routerstatus_t {
-  routerstatus_t status;
-  uint64_t flags;
-  char *version;
+  routerstatus_t status; /**< Underlying 'status' object for this router.
+                          * Flags are redundant. */
+  uint64_t flags; /**< Bit-field for all recognized flags; index into
+                   * networkstatus_vote_t.known_flags. */
+  char *version; /**< The version that the authority says this router is
+                  * running. */
 } vote_routerstatus_t;
 
-/* DOCDOC */
+/* Information about a single voter in a vote or a consensus. */
 typedef struct networkstatus_voter_info_t {
-  char *nickname;
-  char identity_digest[DIGEST_LEN];
-  char *address;
-  uint32_t addr;
-  uint16_t dir_port;
-  uint16_t or_port;
-  char *contact;
-  char vote_digest[DIGEST_LEN];
+  char *nickname; /**< Nickname of this voter */
+  char identity_digest[DIGEST_LEN]; /**< Digest of this voter's identity key */
+  char *address; /**< Address of this voter, in string format. */
+  uint32_t addr; /**< Address of this voter, in IPv4, in host order. */
+  uint16_t dir_port; /**< Directory port of this voter */
+  uint16_t or_port; /**< OR port of this voter */
+  char *contact; /**< Contact information for this voter. */
+  char vote_digest[DIGEST_LEN]; /**< Digest of this voter's vote, as signed. */
+
+  /* DOCDOC */
   char signing_key_digest[DIGEST_LEN]; /* This part is _not_ signed. */
-
   char *signature;
   int signature_len;
   unsigned int bad_signature : 1;
   unsigned int good_signature : 1;
 } networkstatus_voter_info_t;
 
-/*XXXX020 rename to networkstatus_t once it works. */
-/** DOCDOC is vote or consensus. */
+/** A common structure to hold a v2 network status vote, or a v2 network
+ * status consensus. */
+/* XXXX020 rename to networkstatus_t once it replaces networkstatus_t in
+ * functionality. */
 typedef struct networkstatus_vote_t {
-  int is_vote;
-  time_t published; /* vote only. */
-  time_t valid_after;
-  time_t fresh_until;
-  time_t valid_until;
+  int is_vote; /**< True if this is a vote; false if it is a consensus. */
+  time_t published; /**< Vote only: Tiem when vote was written. */
+  time_t valid_after; /**< Time after which this vote or consensus applies. */
+  time_t fresh_until; /**< Time before which this is the most recent vote or
+                       * consensus. */
+  time_t valid_until; /**< Time after which this vote or consensus should not
+                       * be used. */
+
+  /** How long does this vote/consensus claim that authorities take to
+   * distribute their votes to one another? */
   int vote_seconds;
+  /** How long does this vote/consensus claim that authorites take to
+   * distribute their consensus signatures to one another? */
   int dist_seconds;
 
+  /** Comma-separated list of recommended client software, or NULL if this
+   * voter has no opinion. */
   char *client_versions;
   char *server_versions;
+  /** List of flags that this vote/consensus applies to routers.  If a flag is
+   * not listed here, the voter has no opinion on what its value should be. */
   smartlist_t *known_flags;
 
-  smartlist_t *voters; /* list of networkstatus_voter_info_t */
+  /** List of networkstatus_voter_info_t.  For a vote, only one element
+   * is included.  For a consensus, one element is included for every voter
+   * whose vote contributed to the consensus. */
+  smartlist_t *voters;
 
-  struct authority_cert_t *cert; /* vote only. */
+  struct authority_cert_t *cert; /**< Vote only: the voter's certificate. */
 
+  /** Digest of this document, as signed. */
   char networkstatus_digest[DIGEST_LEN];
 
-  smartlist_t *routerstatus_list; /* holds vote_routerstatus_t if is_vote,
-                                   * otherwise just routerstatus_t. */
+  /** List of router statuses, sorted by identity digest.  For a vote,
+   * the elements are vote_routerstatus_t; for a consensus, the elements
+   * are routerstatus_t. */
+  smartlist_t *routerstatus_list;
 } networkstatus_vote_t;
 
-/* XXXX020 merge with networkstatus_vote_t ?? */
-/** DOCDOC */
+/** A set of signatures for a networkstatus consensus.  All fields are as for
+ * networkstatus_vote_t. */
 typedef struct ns_detached_signatures_t {
   time_t valid_after;
   time_t fresh_until;
@@ -1372,21 +1399,29 @@ typedef struct ns_detached_signatures_t {
   smartlist_t *signatures; /* list of networkstatus_voter_info_t */
 } ns_detached_signatures_t;
 
+/** Allowable types of desc_store_t. */
 typedef enum store_type_t {
-  ROUTER_STORE,
-  ANNOTATED_ROUTER_STORE,
-  EXTRAINFO_STORE
+  ROUTER_STORE = 0,
+  EXTRAINFO_STORE = 1
 } store_type_t;
 
-/** DOCDOC */
+/** A 'store' is a set of descriptors saved on disk, with accompanying
+ * journal, mmaped as needed, rebuilt as needed. */
 typedef struct desc_store_t {
+  /** Filename (within DataDir) for the store.  We append .tmp to this
+   * filename for a temporary file when rebuilding the store, and .new to this
+   * filename for the journal. */
   const char *fname_base;
+  /** Alternative (obsolete) value for fname_base: if the file named by
+   * fname_base isn't present, we read from here instead, but we never write
+   * here. */
   const char *fname_alt_base;
+  /** Human-readable description of what this store contains. */
   const char *description;
 
-  tor_mmap_t *mmap;
+  tor_mmap_t *mmap; /**< A mmap for the main file in the store. */
 
-  store_type_t type;
+  store_type_t type; /**< What's stored in this store? */
 
   /** The size of the router log, in bytes. */
   size_t journal_len;
@@ -1416,11 +1451,11 @@ typedef struct {
   /** List of signed_descriptor_t for older router descriptors we're
    * caching. */
   smartlist_t *old_routers;
-  /** DOCDOC Mmaped file holding server descriptors.  If present, any router
-   * whose cache_info.saved_location == SAVED_IN_CACHE is stored in this file
+  /** Store holding server descriptors.  If present, any router whose
+   * cache_info.saved_location == SAVED_IN_CACHE is stored in this file
    * starting at cache_info.saved_offset */
   desc_store_t desc_store;
-  /** Mmaped file holding extra-info documents. */
+  /** Store holding extra-info documents. */
   desc_store_t extrainfo_store;
 } routerlist_t;
 
@@ -2870,7 +2905,7 @@ void ns_detached_signatures_free(ns_detached_signatures_t *s);
 void authority_cert_free(authority_cert_t *cert);
 authority_cert_t *authority_cert_dup(authority_cert_t *cert);
 
-/** DOCDOC */
+/** Describes the schedule by which votes should be generated. */
 typedef struct vote_timing_t {
   int vote_interval;
   int n_intervals_valid;
diff --git a/src/or/rephist.c b/src/or/rephist.c
index f065ad17d..f039d45e1 100644
--- a/src/or/rephist.c
+++ b/src/or/rephist.c
@@ -384,7 +384,8 @@ get_stability(or_history_t *hist, time_t when)
   return total / total_weights;
 }
 
-/** DOCDOC */
+/** Helper: Return the weighted percent-of-time-online of the router with
+ * history <b>hist</b>. */
 static double
 get_weighted_fractional_uptime(or_history_t *hist, time_t when)
 {
@@ -413,7 +414,8 @@ rep_hist_get_stability(const char *id, time_t when)
   return get_stability(hist, when);
 }
 
-/** DOCDOC */
+/** Return an estimated percent-of-time-online for the router whose identity
+ * digest is <b>id</b>. Return 0 if the router is unknown. */
 double
 rep_hist_get_weighted_fractional_uptime(const char *id, time_t when)
 {
diff --git a/src/or/router.c b/src/or/router.c
index b73d420fa..073d2e17d 100644
--- a/src/or/router.c
+++ b/src/or/router.c
@@ -319,7 +319,8 @@ init_v3_authority_keys(const char *keydir)
     authority_cert_free(parsed);
 }
 
-/* DOCDOC */
+/** If we're a v3 authority, check whether we have a certificatge that's
+ * likely to expire soon.  Warn if we do, but not too often. */
 void
 v3_authority_check_key_expiry(void)
 {
@@ -791,7 +792,8 @@ authdir_mode_v3(or_options_t *options)
 {
   return authdir_mode(options) && options->V3AuthoritativeDir != 0;
 }
-/** DOCDOC */
+/** Return true if we belive ourselves to be any kind of non-bridge
+ * authoritative directory  */
 int
 authdir_mode_any_nonbridge(or_options_t *options)
 {
@@ -1773,7 +1775,9 @@ router_reset_warnings(void)
   }
 }
 
-/** DOCDOC */
+/** Given a router purpose, convert it to a string.  Don't call this on
+ * ROUTER_PURPOSE_UNKNOWN: The whole point of that value is that we don't
+ * know its string representation. */
 const char *
 router_purpose_to_string(uint8_t p)
 {
@@ -1788,7 +1792,7 @@ router_purpose_to_string(uint8_t p)
   return NULL;
 }
 
-/** DOCDOC */
+/** Given a string, convert it to a router purpose.  */
 uint8_t
 router_purpose_from_string(const char *s)
 {
diff --git a/src/or/routerlist.c b/src/or/routerlist.c
index 1fe04813e..4da516e0b 100644
--- a/src/or/routerlist.c
+++ b/src/or/routerlist.c
@@ -179,7 +179,7 @@ router_reload_networkstatus(void)
   return 0;
 }
 
-/**DOCDOC */
+/** Read the cached v3 consensus networkstatus from the disk. */
 int
 router_reload_consensus_networkstatus(void)
 {
@@ -363,7 +363,9 @@ trusted_dirs_remove_old_certs(void)
   trusted_dirs_flush_certs_to_disk();
 }
 
-/** DOCDOC */
+/** Return the newest v3 authority certificate whose v3 authority identity key
+ * has digest <b>id_digest</b>.  Return NULL if no such authority is known,
+ * or it has no certificate. */
 authority_cert_t *
 authority_cert_get_newest_by_id(const char *id_digest)
 {
@@ -379,7 +381,9 @@ authority_cert_get_newest_by_id(const char *id_digest)
   return best;
 }
 
-/** DOCDOC */
+/** Return the newest v3 authority certificate whose directory signing key has
+ * giest <sk_digest</b>. Return NULL if no such certificate is known.
+ */
 authority_cert_t *
 authority_cert_get_by_sk_digest(const char *sk_digest)
 {
@@ -416,7 +420,12 @@ authority_cert_get_by_digests(const char *id_digest,
   return NULL;
 }
 
-/** DOCDOC */
+/** Try to download any v3 authority certificates that we may be missing.  If
+ * <b>status</b> is provided, try to get all the ones that were used to sign
+ * <b>status</b>.  Additionally, try to have a non-expired certificate for
+ * every V3 authority in trusted_dir_servers.  Don't fetch certificates we
+ * already have.
+ **/
 void
 authority_certs_fetch_missing(networkstatus_vote_t *status)
 {
@@ -526,6 +535,7 @@ signed_desc_append_to_journal(signed_descriptor_t *desc,
   const char *body = signed_descriptor_get_body_impl(desc,1);
   size_t len = desc->signed_descriptor_len + desc->annotations_len;
 
+  /* XXXX020 remove this; we can now cache things with weird purposes. */
   if (purpose != ROUTER_PURPOSE_GENERAL &&
       purpose != EXTRAINFO_PURPOSE_GENERAL) {
     /* we shouldn't cache it. be happy and return. */
@@ -1983,7 +1993,14 @@ extrainfo_get_by_descriptor_digest(const char *digest)
 
 /** Return a pointer to the signed textual representation of a descriptor.
  * The returned string is not guaranteed to be NUL-terminated: the string's
- * length will be in desc-\>signed_descriptor_len. */
+ * length will be in desc-\>signed_descriptor_len.
+ *
+ * If with_annotations is set, the returned string will include the annotations
+ * (if any) preceding the descriptor.  This will increase the length of the
+ * string by desc-\>annotations_len.
+ *
+ * The caller must not free the string returned.
+ */
 static const char *
 signed_descriptor_get_body_impl(signed_descriptor_t *desc,
                                 int with_annotations)
@@ -2020,7 +2037,12 @@ signed_descriptor_get_body_impl(signed_descriptor_t *desc,
   return r;
 }
 
-/** DOCDOC */
+/** Return a pointer to the signed textual representation of a descriptor.
+ * The returned string is not guaranteed to be NUL-terminated: the string's
+ * length will be in desc-\>signed_descriptor_len.
+ *
+ * The caller must not free the string returned.
+ */
 const char *
 signed_descriptor_get_body(signed_descriptor_t *desc)
 {
@@ -4110,7 +4132,11 @@ networkstatus_get_live_consensus(time_t now)
     return NULL;
 }
 
-/** DOCDOC */
+/** Try to replace the current cached v3 networkstatus with the one in
+ * <b>consensus</b>.  If we don't have enough certificates to validate it,
+ * store it in consensus_waiting_for_certs and launch a certificate fetch.
+ *
+ * Return 0 on success, -1 on failure. */
 int
 networkstatus_set_current_consensus(const char *consensus, int from_cache,
                                     int was_waiting_for_certs)
@@ -4146,9 +4172,12 @@ networkstatus_set_current_consensus(const char *consensus, int from_cache,
                        options->DataDirectory);
           write_str_to_file(filename, consensus, 0);
         }
-        /* XXXX020 trigger the certificate download. */
+        /* XXXX this test isn't quite right; see below. */
+        if (!connection_get_by_type_purpose(CONN_TYPE_DIR,
+                                            DIR_PURPOSE_FETCH_CERTIFICATE))
+          authority_certs_fetch_missing(c);
       }
-      return -1;
+      return -1; /* XXXX020 shoul*/
     } else {
       if (!was_waiting_for_certs)
         log_warn(LD_DIR, "Not enough good signatures on networkstatus "
@@ -4158,6 +4187,14 @@ networkstatus_set_current_consensus(const char *consensus, int from_cache,
     }
   }
 
+  /* Are we missing any certificates at all? */
+  /* XXXX The test for 'are we downloading' should be 'are we downloading
+   *    these certificates', and it should get pushed into
+   *    authority_certs_fetch_missing. */
+  if (r != 1 && !connection_get_by_type_purpose(CONN_TYPE_DIR,
+                                                DIR_PURPOSE_FETCH_CERTIFICATE))
+    authority_certs_fetch_missing(c);
+
   if (current_consensus)
     networkstatus_vote_free(current_consensus);
 
diff --git a/src/or/routerparse.c b/src/or/routerparse.c
index 652622480..1ab5e73e9 100644
--- a/src/or/routerparse.c
+++ b/src/or/routerparse.c
@@ -143,7 +143,7 @@ typedef struct token_rule_t {
   /** One or more of AT_START/AT_END to limit where the item may appear in a
    * document. */
   int pos;
-  /** DOCDOC */
+  /** True iff this token is an annotation. */
   int is_annotation;
 } token_rule_t;
 
@@ -855,7 +855,11 @@ check_signature_token(const char *digest,
   return 0;
 }
 
-/** DOCDOC */
+/** Helper: move *<b>s_ptr</b> ahead to the next router, the next extra-info,
+ * or to the first of the annotations proceeding the next router or
+ * extra-info---whichever comes first.  Set <b>is_extrainfo_out</b> to true if
+ * we found an extrainfo, or false if found a router. Do not scan beyond
+ * <b>eos</b>.  Return -1 if we found nothing; 0 if we found something. */
 static int
 find_start_of_next_router_or_extrainfo(const char **s_ptr,
                                        const char *eos,
@@ -1005,7 +1009,14 @@ dump_distinct_digest_count(int severity)
  * returns NULL.  If <b>cache_copy</b> is true, duplicate the contents of
  * s through end into the signed_descriptor_body of the resulting
  * routerinfo_t.
- * DOCDOC annotations
+ *
+ * If <b>allow_annotations</b>, it's okay to encounter annotations in <b>s</b>
+ * before the router; if it's false, reject the router if it's annotated.  If
+ * <b>prepend_annotations</b> is set, it should contain some annotations:
+ * append them to the front of the router before parsing it, and keep them
+ * around when caching the router.
+ *
+ * Only one of allow_annotations and prepend_annotations may be set.
  */
 routerinfo_t *
 router_parse_entry_from_string(const char *s, const char *end,
@@ -1531,7 +1542,11 @@ find_start_of_next_routerstatus(const char *s)
 /** Given a string at *<b>s</b>, containing a routerstatus object, and an
  * empty smartlist at <b>tokens</b>, parse and return the first router status
  * object in the string, and advance *<b>s</b> to just after the end of the
- * router status.  Return NULL and advance *<b>s</b> on error. */
+ * router status.  Return NULL and advance *<b>s</b> on error.
+ *
+ * If <b>vote</b> and <b>vote_rs</b> are provided, don't allocate a fresh
+ * routerstatus but use <b>vote_rs</b> instead
+ **/
 static routerstatus_t *
 routerstatus_parse_entry_from_string(const char **s, smartlist_t *tokens,
                                      networkstatus_vote_t *vote,