add docs, fix whitespace, and make ANY rule in routerparse a little tighter.

svn:r5031

6 files changed, 111 insertions, 70 deletions

diff --git a/src/or/directory.c b/src/or/directory.c
index c386b20d28..43eb9592c7 100644
--- a/src/or/directory.c
+++ b/src/or/directory.c
@@ -283,27 +283,33 @@ connection_dir_request_failed(connection_t *conn)
   }
 }
 
-/** DOCDOC */
+/** Called when an attempt to download one or network status documents
+ * on connection <b>conn</b> failed.
+ */
 static void
 connection_dir_download_networkstatus_failed(connection_t *conn)
 {
-    if (!strcmpstart(conn->requested_resource, "all")) {
-      directory_get_from_dirserver(conn->purpose, "all.z",
-                                   0 /* don't retry_if_no_servers */);
-    } else if (!strcmpstart(conn->requested_resource, "fp/")) {
-      smartlist_t *failed = smartlist_create();
-      smartlist_split_string(failed, conn->requested_resource+3, "+", 0, 0);
-      if (smartlist_len(failed)) {
-        char *last = smartlist_get(failed,smartlist_len(failed)-1);
-        size_t last_len = strlen(last);
-        if (!strcmp(last+last_len-2, ".z"))
-          last[last_len-2] = '\0';
-
-        dir_networkstatus_download_failed(failed);
-        SMARTLIST_FOREACH(failed, char *, cp, tor_free(cp));
-      }
-      smartlist_free(failed);
+  if (!strcmpstart(conn->requested_resource, "all")) {
+    /* We're a non-authoritative directory cache; try again. */
+    directory_get_from_dirserver(conn->purpose, "all.z",
+                                 0 /* don't retry_if_no_servers */);
+  } else if (!strcmpstart(conn->requested_resource, "fp/")) {
+    /* We were trying to download by fingerprint; mark them all has having
+     * failed, and possibly retry them later.*/
+    smartlist_t *failed = smartlist_create();
+    /* XXXX NM this splitting logic is duplicated someplace. Fix that. */
+    smartlist_split_string(failed, conn->requested_resource+3, "+", 0, 0);
+    if (smartlist_len(failed)) {
+      char *last = smartlist_get(failed,smartlist_len(failed)-1);
+      size_t last_len = strlen(last);
+      if (!strcmp(last+last_len-2, ".z"))
+        last[last_len-2] = '\0';
+
+      dir_networkstatus_download_failed(failed);
+      SMARTLIST_FOREACH(failed, char *, cp, tor_free(cp));
     }
+    smartlist_free(failed);
+  }
 }
 
 /** Helper for directory_initiate_command_(router|trusted_dir): send the
@@ -1492,7 +1498,9 @@ connection_dir_finished_connecting(connection_t *conn)
   return 0;
 }
 
-/** DOCDOC */
+/** Called when one or more networkstatus fetches have failed (with uppercase
+ * fingerprints listed in <b>fp</>).  Mark those fingerprints has having
+ * failed once. */
 static void
 dir_networkstatus_download_failed(smartlist_t *failed)
 {
diff --git a/src/or/dirserv.c b/src/or/dirserv.c
index 9eb576b728..d34186a4bb 100644
--- a/src/or/dirserv.c
+++ b/src/or/dirserv.c
@@ -773,9 +773,9 @@ dirserv_set_cached_directory(const char *directory, time_t published,
 
 /** We've just received a v2 network-status for an authoritative directory
  * with fingerprint <b>fp</b> (hex digest, no spaces), published at
- * <b>published</b>.  Store it so we can serve it to others.
- *
- * DOCDOC directory==NULL, published==0
+ * <b>published</b>.  Store it so we can serve it to others.  If
+ * <b>directory</b> is NULL, remove the entry with the given fingerprint from
+ * the cache.
  */
 void
 dirserv_set_cached_networkstatus_v2(const char *directory, const char *fp,
@@ -803,6 +803,11 @@ dirserv_set_cached_networkstatus_v2(const char *directory, const char *fp,
   }
 }
 
+/** Helper: If we're an authority for the right directory version (the
+ * directory version is determined by <b>is_v1_object</b>), try to regenerate
+ * auth_src as appropriate and return it, falling back to cache_src on
+ * failure.  If we're a cache, return cach_src.
+ */
 static cached_dir_t *
 dirserv_pick_cached_dir_obj(cached_dir_t *cache_src,
                             cached_dir_t *auth_src,
@@ -837,9 +842,10 @@ dirserv_pick_cached_dir_obj(cached_dir_t *cache_src,
  * DIR_REGEN_SLACK_TIME seconds, call <b>regenerate</b>() to make a fresh one.
  * Yields the compressed version of the directory object if <b>compress</b> is
  * set; otherwise return the uncompressed version.  (In either case, sets
- * *<b>out</b> and returns the size of the buffer in *<b>out</b>.
+ * *<b>out</b> and returns the size of the buffer in *<b>out</b>.)
  *
- * DOCDOC is_v1_object
+ * Use <b>is_v1_object</b> to help determine whether we're authoritative for
+ * this kind of object.
  **/
 static size_t
 dirserv_get_obj(const char **out, int compress,
diff --git a/src/or/or.h b/src/or/or.h
index cd51a0624e..b102e766ba 100644
--- a/src/or/or.h
+++ b/src/or/or.h
@@ -2020,14 +2020,18 @@ void router_free_all_keys(void);
 
 /********************************* routerlist.c ***************************/
 
+/** Represents information about a single trusted directory server. */
 typedef struct trusted_dir_server_t {
-  char *address;
-  uint32_t addr;
-  uint16_t dir_port;
-  char digest[DIGEST_LEN];
-  unsigned int is_running:1;
-  unsigned int supports_v1_protocol:1;
-  int n_networkstatus_failures;
+  char *address; /**< Hostname */
+  uint32_t addr; /**< IPv4 address */
+  uint16_t dir_port; /**< Directory port */
+  char digest[DIGEST_LEN]; /**< Digest of identity key */
+  unsigned int is_running:1; /**< True iff we think this server is running. */
+  unsigned int supports_v1_protocol:1; /**< True iff this server is an
+                                        * authority for the older ("v1")
+                                        * directory protocol.*/
+  int n_networkstatus_failures; /**< How many times have we asked for this
+                                 * server's network-status unsuccessfully? */
 } trusted_dir_server_t;
 
 int router_reload_router_list(void);
diff --git a/src/or/routerlist.c b/src/or/routerlist.c
index 38124d2265..85446a8075 100644
--- a/src/or/routerlist.c
+++ b/src/or/routerlist.c
@@ -119,29 +119,44 @@ router_reload_networkstatus(void)
   return 0;
 }
 
-/* DOCDOC */
-static size_t router_log_len = 0;
+/* Router descriptor storage.
+ *
+ * Routerdescs are stored in a big file, named "cached-routers".  As new
+ * routerdescs arrive, we append them to a journal file named
+ * "cached-routers.jrn".
+ *
+ * From time to time, we replace "cached-routers" with a new file containing
+ * only the live, non-superseded descriptors, and clear cached-routers.log.
+ *
+ * On startup, we read both files.
+ */
+
+/** The size of the router log, in bytes. */
+static size_t router_journal_len = 0;
+/** The size of the router store, in bytes. */
 static size_t router_store_len = 0;
 
-/* DOCDOC */
+/** Helper: return 1 iff the router log is so big we want to rebuild the
+ * store. */
 static int
 router_should_rebuild_store(void)
 {
   if (router_store_len > (1<<16))
-    return router_log_len > router_store_len / 2;
+    return router_journal_len > router_store_len / 2;
   else
-    return router_log_len > (1<<15);
+    return router_journal_len > (1<<15);
 }
 
-/* DOCDOC */
+/** Add the <b>len</b>-type router descriptor in <b>s</b> to the router
+ * journal. */
 int
-router_append_to_log(const char *s, size_t len)
+router_append_to_journal(const char *s, size_t len)
 {
   or_options_t *options = get_options();
   size_t fname_len = strlen(options->DataDirectory)+32;
   char *fname = tor_malloc(len);
 
-  tor_snprintf(fname, fname_len, "%s/cached-routers.log",
+  tor_snprintf(fname, fname_len, "%s/cached-routers.new",
                options->DataDirectory);
 
   if (!len)
@@ -158,7 +173,10 @@ router_append_to_log(const char *s, size_t len)
   return 0;
 }
 
-/* DOCDOC */
+/** If the journal is too long, or if <b>force</b> is true, then atomically
+ * replace the router store with the routers currently in our routerlist, and
+ * clear the journal.  Return 0 on success, -1 on failure.
+ */
 int
 router_rebuild_store(int force)
 {
@@ -199,7 +217,7 @@ router_rebuild_store(int force)
     goto done;
   }
 
-  tor_snprintf(fname, fname_len, "%s/cached-routers.log",
+  tor_snprintf(fname, fname_len, "%s/cached-routers.new",
                options->DataDirectory);
 
   write_str_to_file(fname, "", 0);
@@ -216,7 +234,7 @@ router_rebuild_store(int force)
   return r;
 }
 
-/* Set *<b>outp</b> to a smartlist containing a list of
+/** Set *<b>outp</b> to a smartlist containing a list of
  * trusted_dir_server_t * for all known trusted dirservers.  Callers
  * must not modify the list or its contents.
  */
diff --git a/src/or/routerparse.c b/src/or/routerparse.c
index e7c9ca3535..6e3a398f7c 100644
--- a/src/or/routerparse.c
+++ b/src/or/routerparse.c
@@ -83,26 +83,27 @@ typedef struct directory_token_t {
 
 /** Rules for how many arguments a keyword can take. */
 typedef enum {
-  NO_ARGS,     /**<    (1) no arguments, ever */
-  ARGS,        /**<    (2) a list of arguments separated by spaces */
-  CONCAT_ARGS, /**< or (3) the rest of the line, treated as a single argument. */
+  NO_ARGS,     /**< No arguments, ever */
+  ARGS,        /**< A list of arguments separated by spaces */
+  CONCAT_ARGS, /**< The rest of the line, treated as a single argument. */
 } arg_syntax;
 
 /** Rules for whether the keyword needs an object. */
 typedef enum {
-  NO_OBJ,      /**<    (1) no object, ever */
-  NEED_OBJ,    /**<    (2) object is required */
-  NEED_KEY,    /**<    (3) object is required, and must be a public key. */
-  OBJ_OK,      /**< or (4) object is optional. */
+  NO_OBJ,      /**< No object, ever */
+  NEED_OBJ,    /**< Object is required */
+  NEED_KEY,    /**< Object is required, and must be a public key. */
+  OBJ_OK,      /**< Object is optional. */
 } obj_syntax;
 
 /** Rules for where a keyword can appear. */
 typedef enum {
-  DIR = 1,   /**< Appears only in directory. */
-  RTR = 2,   /**< Appears only in router descriptor or runningrouters */
+  DIR = 1,        /**< Appears only in directory. */
+  RTR = 2,        /**< Appears only in router descriptor or runningrouters */
   NETSTATUS = 4,  /**< v2 or later ("versioned") network status. */
-  RTRSTATUS = 8,
-  ANY = 15,    /**< Appears in router descriptor or in directory sections. */
+  ANYSIGNED = 7,  /**< Any "full" document (that is, not a router status.) */
+  RTRSTATUS = 8,  /**< Router-status portion of a versioned network status. */
+  ANY = 15,       /**< Appears in any document type */
 } where_syntax;
 
 /** Table mapping keywords to token value and to argument rules. */
@@ -111,9 +112,9 @@ static struct {
 } token_table[] = {
   { "accept",              K_ACCEPT,              ARGS,    NO_OBJ,  RTR },
   { "directory-signature", K_DIRECTORY_SIGNATURE, ARGS,    NEED_OBJ,
-    DIR|NETSTATUS},
-  { "r",                   K_R,                   ARGS,    NO_OBJ,  RTRSTATUS },
-  { "s",                   K_S,                   ARGS,    NO_OBJ,  RTRSTATUS },
+                                                           DIR|NETSTATUS},
+  { "r",                   K_R,                   ARGS,    NO_OBJ, RTRSTATUS },
+  { "s",                   K_S,                   ARGS,    NO_OBJ, RTRSTATUS },
   { "reject",              K_REJECT,              ARGS,    NO_OBJ,  RTR },
   { "router",              K_ROUTER,              ARGS,    NO_OBJ,  RTR },
   { "recommended-software",K_RECOMMENDED_SOFTWARE,ARGS,    NO_OBJ,  DIR },
@@ -126,14 +127,15 @@ static struct {
   { "ports",               K_PORTS,               ARGS,    NO_OBJ,  RTR },
   { "bandwidth",           K_BANDWIDTH,           ARGS,    NO_OBJ,  RTR },
   { "platform",            K_PLATFORM,        CONCAT_ARGS, NO_OBJ,  RTR },
-  { "published",           K_PUBLISHED,       CONCAT_ARGS, NO_OBJ,  ANY },
-  { "opt",                 K_OPT,             CONCAT_ARGS, OBJ_OK,  ANY },
-  { "contact",             K_CONTACT,         CONCAT_ARGS, NO_OBJ,  ANY },
+  { "published",           K_PUBLISHED,       CONCAT_ARGS, NO_OBJ, ANYSIGNED },
+  { "opt",                 K_OPT,             CONCAT_ARGS, OBJ_OK, ANY },
+  { "contact",             K_CONTACT,         CONCAT_ARGS, NO_OBJ, ANYSIGNED },
   { "network-status",      K_NETWORK_STATUS,      NO_ARGS, NO_OBJ,  DIR },
   { "uptime",              K_UPTIME,              ARGS,    NO_OBJ,  RTR },
-  { "dir-signing-key",     K_DIR_SIGNING_KEY,     ARGS,    OBJ_OK, DIR|NETSTATUS},
+  { "dir-signing-key",     K_DIR_SIGNING_KEY,     ARGS,    OBJ_OK,
+                                                                DIR|NETSTATUS},
   { "family",              K_FAMILY,              ARGS,    NO_OBJ,  RTR },
-  { "fingerprint",         K_FINGERPRINT,         ARGS,    NO_OBJ,  ANY },
+  { "fingerprint",         K_FINGERPRINT,         ARGS,    NO_OBJ, ANYSIGNED },
   { "hibernating",         K_HIBERNATING,         ARGS,    NO_OBJ,  RTR },
   { "read-history",        K_READ_HISTORY,        ARGS,    NO_OBJ,  RTR },
   { "write-history",       K_WRITE_HISTORY,       ARGS,    NO_OBJ,  RTR },
@@ -169,7 +171,7 @@ static crypto_pk_env_t *find_dir_signing_key(const char *str);
 static int tor_version_same_series(tor_version_t *a, tor_version_t *b);
 
 /** Set <b>digest</b> to the SHA-1 digest of the hash of the directory in
- * <b>s</b>.  Return 0 on success, nonzero on failure.
+ * <b>s</b>.  Return 0 on success, -1 on failure.
  */
 int
 router_get_dir_hash(const char *s, char *digest)
@@ -179,7 +181,7 @@ router_get_dir_hash(const char *s, char *digest)
 }
 
 /** Set <b>digest</b> to the SHA-1 digest of the hash of the first router in
- * <b>s</b>. Return 0 on success, nonzero on failure.
+ * <b>s</b>. Return 0 on success, -1 on failure.
  */
 int
 router_get_router_hash(const char *s, char *digest)
@@ -189,7 +191,7 @@ router_get_router_hash(const char *s, char *digest)
 }
 
 /** Set <b>digest</b> to the SHA-1 digest of the hash of the running-routers
- * string in <b>s</b>. Return 0 on success, nonzero on failure.
+ * string in <b>s</b>. Return 0 on success, -1 on failure.
  */
 int
 router_get_runningrouters_hash(const char *s, char *digest)
@@ -198,12 +200,13 @@ router_get_runningrouters_hash(const char *s, char *digest)
                               "network-status","\ndirectory-signature");
 }
 
-/** DOCDOC */
+/** Set <b>digest</b> to the SHA-1 digest of the hash of the network-status
+ * string in <b>s</b>.  Return 0 on success, -1 on failure. */
 int
 router_get_networkstatus_v2_hash(const char *s, char *digest)
 {
   return router_get_hash_impl(s,digest,
-                              "network-status-version","\ndirectory-signature");
+                            "network-status-version","\ndirectory-signature");
 }
 
 /** Helper: used to generate signatures for routers, directories and
@@ -1477,7 +1480,9 @@ router_parse_addr_policy_from_string(const char *s, int assume_action)
   return r;
 }
 
-/** DOCDOC */
+/** Given an exit policicy stored in <b>s</b>, parse it and add it to the end
+ * of the exit policy of <b>router</b>.  Return 0 on success, -1 on failure.
+ */
 int
 router_add_exit_policy_from_string(routerinfo_t *router, const char *s)
 {
@@ -1492,9 +1497,10 @@ router_add_exit_policy_from_string(routerinfo_t *router, const char *s)
   return 0;
 }
 
-/** DOCDOC */
+/** Add an exit policy stored in the token <b>tok</b> to the router info in
+ * <b>router</b>.  Return 0 on success, -1 on failure. */
 static int
-router_add_exit_policy(routerinfo_t *router,directory_token_t *tok)
+router_add_exit_policy(routerinfo_t *router, directory_token_t *tok)
 {
   addr_policy_t *newe, **tmpe;
   newe = router_parse_addr_policy(tok);
@@ -1556,7 +1562,7 @@ policy_read_failed:
   return NULL;
 }
 
-/** log and exit if <b>t</b> is malformed */
+/** Log and exit if <b>t</b> is malformed */
 void
 assert_addr_policy_ok(addr_policy_t *t)
 {
diff --git a/src/or/test.c b/src/or/test.c
index 9edab2b137..f529ca551b 100644
--- a/src/or/test.c
+++ b/src/or/test.c
@@ -88,7 +88,6 @@ remove_directory(void)
     smartlist_free(elements);
   }
   rmdir(temp_dir);
-  
 }
 
 static void