r15560@tombo: nickm | 2007-12-18 23:18:21 -0500

 Add a bit of missing documentation.


svn:r12869

3 files changed, 39 insertions, 19 deletions

diff --git a/doc/tor.1.in b/doc/tor.1.in
index 4513742947..bf270900c5 100644
--- a/doc/tor.1.in
+++ b/doc/tor.1.in
@@ -718,6 +718,13 @@ documents contain information about servers other than the information
 in their regular router descriptors.  Tor does not use this information for
 anything itself; to save bandwidth, leave this option turned off.
 (Default: 0).
+.LP
+.TP
+\fBFallbackNetworkstatusFile\fP \fIFILENAME\fP
+If Tor doesn't have a cached networkstatus file, it starts out uses
+this one instead.  Even if this file is out of date, Tor can still use
+it to learn about directory mirrors, so it doesn't need to put load on
+the authorities.  (Default: None).
 
 .LP
 .TP
diff --git a/src/or/or.h b/src/or/or.h
index 682d83d019..34a7c26d86 100644
--- a/src/or/or.h
+++ b/src/or/or.h
@@ -1178,7 +1178,8 @@ typedef enum {
   SAVED_IN_JOURNAL
 } saved_location_t;
 
-/** DOCDOC */
+/** Enumeration: what kind of downlaod schedule are we using for a given
+ * object? */
 typedef enum {
   DL_SCHED_GENERIC = 0,
   DL_SCHED_CONSENSUS = 1,
@@ -1191,7 +1192,7 @@ typedef struct download_status_t {
                            * again? */
   uint8_t n_download_failures; /**< Number of failures trying to download the
                                 * most recent descriptor. */
-  download_schedule_t schedule : 1;
+  download_schedule_t schedule : 8;
 } download_status_t;
 
 /** The max size we expect router descriptor annotations we create to
@@ -1462,12 +1463,15 @@ typedef struct networkstatus_voter_info_t {
   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;
+  /* Nothing from here on is signed. */
+  char signing_key_digest[DIGEST_LEN]; /**< Declared digest of signing key
+                                        * used by this voter. */
+  char *signature; /**< Signature from this voter. */
+  int signature_len; /**< Length of <b>signature</b> */
+  unsigned int bad_signature : 1; /**< Set to true if we've verified the sig
+                                   * as good. */
+  unsigned int good_signature : 1; /**< Set to true if we've tried to verify
+                                    * the sig, and we know it's bad. */
 } networkstatus_voter_info_t;
 
 /** A common structure to hold a v2 network status vote, or a v2 network
@@ -2309,10 +2313,12 @@ typedef struct {
   /** The number of intervals we think a consensus should be valid. */
   int V3AuthNIntervalsValid;
 
-  /** DOCDOC here and in tor.1 */
+  /** File to check for a consensus networkstatus, if we don't have one
+   * cached. */
   char *FallbackNetworkstatusFile;
 
   /** DOCDOC here and in tor.1 */
+  /**XXXX020 make this always on? */
   int LearnAuthorityAddrFromCerts;
 
   /** DOCDOC here and in tor.1 */
@@ -2636,10 +2642,15 @@ int options_save_current(void);
 const char *get_torrc_fname(void);
 char *get_datadir_fname2_suffix(const char *sub1, const char *sub2,
                                 const char *suffix);
-/**DOCDOC*/
+/** Return a newly allocated string containing datadir/sub1.  See
+ * get_datadir_fname2_suffix.  */
 #define get_datadir_fname(sub1) get_datadir_fname2_suffix((sub1), NULL, NULL)
+/** Return a newly allocated string containing datadir/sub1/sub2.  See
+ * get_datadir_fname2_suffix.  */
 #define get_datadir_fname2(sub1,sub2) \
   get_datadir_fname2_suffix((sub1), (sub2), NULL)
+/** Return a newly allocated string containing datadir/sub1suffix.  See
+ * get_datadir_fname2_suffix. */
 #define get_datadir_fname_suffix(sub1, suffix) \
   get_datadir_fname2_suffix((sub1), NULL, (suffix))
 
@@ -3023,9 +3034,10 @@ time_t download_status_increment_failure(download_status_t *dls,
                                     get_options()->DirPort, time(NULL))
 
 void download_status_reset(download_status_t *dls);
-/** DOCDOC */
 static int download_status_is_ready(download_status_t *dls, time_t now,
                                     int max_failures);
+/** Return true iff, as of <b>now</b>, the resource tracked by <b>dls</b> is
+ * ready to get its download reattempted. */
 static INLINE int
 download_status_is_ready(download_status_t *dls, time_t now,
                          int max_failures)
diff --git a/src/or/routerlist.c b/src/or/routerlist.c
index 87cf78f61d..e66f8c0b12 100644
--- a/src/or/routerlist.c
+++ b/src/or/routerlist.c
@@ -2769,8 +2769,8 @@ router_add_to_routerlist(routerinfo_t *router, const char **msg,
 }
 
 /** Insert <b>ei</b> into the routerlist, or free it. Other arguments are
- * as for router_add_to_routerlist().
- * DOCDOC Inserted
+ * as for router_add_to_routerlist().  Return true iff we actually inserted
+ * it.
  */
 int
 router_add_extrainfo_to_routerlist(extrainfo_t *ei, const char **msg,
@@ -3962,7 +3962,8 @@ static int have_min_dir_info = 0;
  * enough directory info to build circuits that our old answer can no longer
  * be trusted. */
 static int need_to_update_have_min_dir_info = 1;
-/** DOCDOC */
+/** String describing what we're missing before we have enough directory
+ * info. */
 static char dir_info_status[128] = "";
 
 /** Return true iff we have enough networkstatus and router information to
@@ -3989,7 +3990,8 @@ router_dir_info_changed(void)
   need_to_update_have_min_dir_info = 1;
 }
 
-/** DOCDOC */
+/** Return a string describing what we're missing before we have enough
+ * directory info. */
 const char *
 get_dir_info_status_string(void)
 {
@@ -4166,14 +4168,13 @@ router_differences_are_cosmetic(routerinfo_t *r1, routerinfo_t *r2)
   return 1;
 }
 
-/** Check whether <b>ri</b> is a router compatible with the extrainfo document
+/** Check whether <b>ri</b> (a.k.a. sd) is a router compatible with the
+ * extrainfo document
  * <b>ei</b>.  If no router is compatible with <b>ei</b>, <b>ei</b> should be
  * dropped.  Return 0 for "compatible", return 1 for "reject, and inform
  * whoever uploaded <b>ei</b>, and return -1 for "reject silently.".  If
  * <b>msg</b> is present, set *<b>msg</b> to a description of the
- * incompatibility (if any)
- *
- * DOCDOC sd.  DOCDOC extrainfo_is_bogus.
+ * incompatibility (if any).
  **/
 int
 routerinfo_incompatible_with_extrainfo(routerinfo_t *ri, extrainfo_t *ei,