r15905@catbus: nickm | 2007-10-18 09:58:54 -0400

 Document some functions while I can still rememberf what they do.  Fix up some whitespace.


svn:r12018

src/or/config.c

@@ -4363,7 +4363,6 @@ get_datadir_fname2_suffix(const char *sub1, const char *sub2,
   return fname;
 }
 
-
 /** Return 0 if every setting in <b>state</b> is reasonable, and a
  * permissible transition from <b>old_state</b>.  Else warn and return -1.
  * Should have no side effects, except for normalizing the contents of

src/or/directory.c

@@ -2716,7 +2716,10 @@ dir_networkstatus_download_failed(smartlist_t *failed, int status_code)
   });
 }
 
-/** DOCDOC */
+/** Called when an attempt to download <b>dls</b> has failed with HTTP status
+ * <b>status_code</b>.  Increment the failure count (if the code indicates a
+ * real failure) and set <b>dls<b>->next_attempt_at to an appropriate time in
+ * the future. */
 time_t
 download_status_increment_failure(download_status_t *dls, int status_code,
                                   const char *item, int server, time_t now)
@@ -2761,7 +2764,8 @@ download_status_increment_failure(download_status_t *dls, int status_code,
   return dls->next_attempt_at;
 }
 
-/** DOCDOC */
+/** Reset <b>dls</b> so that it will be considered downloadable
+ * immediately. */
 void
 download_status_reset(download_status_t *dls)
 {

src/or/dirvote.c

@@ -1474,7 +1474,6 @@ dirvote_add_vote(const char *vote_body, const char **msg_out, int *status_out)
     }
   }
 
-
   return any_failed ? NULL : pending_vote;
 }
 

src/or/networkstatus.c

@@ -7,22 +7,26 @@ const char networkstatus_c_id[] =
   "$Id$";
 
 /**
- * DOCDOC
+ * \file Functions and structures for handling network status documents as a
+ * client or cache.
  */
 
 #include "or.h"
 
-/** XXXXX020 are all these still needed */
+/* For tracking v2 networkstatus documents.  Only caches do this now. */
 
-/** DOCDOC */
+/** Map from descriptor digest of routers listed in the v2 networkstatus
+ * documents to download_status_t* */
 static digestmap_t *v2_download_status_map = NULL;
-
-/** Map from lowercase nickname to digest of named server, if any. */
-static strmap_t *named_server_map = NULL;
-
 /** Global list of all of the current v2 network_status documents that we know
  * about.  This list is kept sorted by published_on. */
 static smartlist_t *networkstatus_v2_list = NULL;
+/** True iff any member of networkstatus_v2_list has changed since the last
+ * time we called download_status_map_update_from_v2_networkstatus() */
+static int networkstatus_v2_list_has_changed = 0;
+
+/** Map from lowercase nickname to digest of named server, if any. */
+static strmap_t *named_server_map = NULL;
 
 /** Most recently received and validated v3 consensus network status. */
 static networkstatus_vote_t *current_consensus = NULL;
@@ -32,18 +36,16 @@ static networkstatus_vote_t *current_consensus = NULL;
 static networkstatus_vote_t *consensus_waiting_for_certs = NULL;
 static char *consensus_waiting_for_certs_body = NULL;
 
-/** True iff any member of networkstatus_v2_list has changed since the last
- * time we called routerstatus_list_update_from_networkstatus(). */
-static int networkstatus_v2_list_has_changed = 0;
-
 /** The last time we tried to download a networkstatus, or 0 for "never".  We
  * use this to rate-limit download attempts for directory caches (including
  * mirrors).  Clients don't use this now. */
 static time_t last_networkstatus_download_attempted = 0;
 
-/**DOCDOC*/
+/** A time before which we shouldn't try to replace the current consensus:
+ * this will be at some point after the next consensus becomes valid, but
+ * before the current consensus becomes invalid. */
 static time_t time_to_download_next_consensus = 0;
-/**DOCDOC*/
+/** Download status for the current consensus networkstatus. */
 static download_status_t consensus_dl_status = { 0, 0};
 
 /** List of strings for nicknames or fingerprints we've already warned about
@@ -60,10 +62,11 @@ static int have_warned_about_old_version = 0;
  * listed by the authorities  */
 static int have_warned_about_new_version = 0;
 
-static void routerstatus_list_update_from_v2_networkstatus(void);
+static void download_status_map_update_from_v2_networkstatus(void);
 static void routerstatus_list_update_named_server_map(void);
 
-/** DOCDOC */
+/** Forget that we've warned about anything networkstatus-related, so we will
+ * give fresh warnings if the same behavior happens again. */
 void
 networkstatus_reset_warnings(void)
 {
@@ -520,7 +523,7 @@ networkstatus_vote_find_entry(networkstatus_vote_t *ns, const char *digest)
                            _compare_digest_to_routerstatus_entry);
 }
 
-/** DOCDOC */
+/** Return a list of the v2 networkstatus documents. */
 const smartlist_t *
 networkstatus_get_v2_list(void)
 {
@@ -547,7 +550,8 @@ router_get_consensus_status_by_descriptor_digest(const char *digest)
   return digestmap_get(current_consensus->desc_digest_map, digest);
 }
 
-/** DOCDOC */
+/** Given the digest of a router descriptor, return its current download
+ * status, or NULL if the digest is unrecognized. */
 download_status_t *
 router_get_dl_status_by_descriptor_digest(const char *d)
 {
@@ -648,7 +652,8 @@ router_get_consensus_status_by_nickname(const char *nickname,
   return best;
 }
 
-/** DOCDOC */
+/** Return the identity digest that's mapped to officially by
+ * <b>nickname</b>. */
 const char *
 networkstatus_get_router_digest_by_nickname(const char *nickname)
 {
@@ -723,28 +728,31 @@ update_v2_networkstatus_cache_downloads(time_t now)
   }
 }
 
-/** DOCDOC */
+/** If we want to download a fresh consensus, launch a new download as
+ * appropriate.  */
 static void
 update_consensus_networkstatus_downloads(time_t now)
 {
   or_options_t *options = get_options();
   if (!networkstatus_get_live_consensus(now))
-    time_to_download_next_consensus = now;
+    time_to_download_next_consensus = now; /* No live consensus? Get one now!*/
   if (time_to_download_next_consensus > now)
-    return;
+    return; /* Wait until the current consensus is older. */
   if (authdir_mode_v3(options))
-    return;
+    return; /* Authorities never fetch a consensus */
+  /*XXXX020 magic number 8.*/
   if (!download_status_is_ready(&consensus_dl_status, now, 8))
-    return; /*XXXX020 magic number 8.*/
+    return; /* We failed downloading a consensus too recently. */
   if (connection_get_by_type_purpose(CONN_TYPE_DIR,
                                      DIR_PURPOSE_FETCH_CONSENSUS))
-    return;
+    return; /* There's an in-progress download.*/
 
   directory_get_from_dirserver(DIR_PURPOSE_FETCH_CONSENSUS,
                                ROUTER_PURPOSE_GENERAL, NULL, 1);
 }
 
-/** DOCDOC */
+/** Called when an attempt to download a consensus fails: note that the
+ * failure occurred, and possibly retry. */
 void
 networkstatus_consensus_download_failed(int status_code)
 {
@@ -753,7 +761,8 @@ networkstatus_consensus_download_failed(int status_code)
   update_consensus_networkstatus_downloads(time(NULL));
 }
 
-/** DOCDOC */
+/** Update the time at which we'll consider replacing the current
+ * consensus. */
 static void
 update_consensus_networkstatus_fetch_time(time_t now)
 {
@@ -851,7 +860,8 @@ networkstatus_get_live_consensus(time_t now)
     return NULL;
 }
 
-/** DOCDOC */
+/** Copy all the ancillary information (like router download status and so on)
+ * from <b>old_c</b> to <b>new_c</b> */
 static void
 networkstatus_copy_old_consensus_info(networkstatus_vote_t *new_c,
                                       const networkstatus_vote_t *old_c)
@@ -999,7 +1009,8 @@ networkstatus_set_current_consensus(const char *consensus, int from_cache,
   return result;
 }
 
-/** DOCDOC */
+/** Called when we have gotten more certificates: see whether we can
+ * now verify a pending consensus. */
 void
 networkstatus_note_certs_arrived(void)
 {
@@ -1027,10 +1038,8 @@ routers_update_all_from_networkstatus(time_t now)
 
   router_dir_info_changed(); /*XXXX020 really? */
 
-  if (networkstatus_v2_list_has_changed) {
-    routerstatus_list_update_from_v2_networkstatus();
-    networkstatus_v2_list_has_changed = 0;
-  }
+  if (networkstatus_v2_list_has_changed)
+    download_status_map_update_from_v2_networkstatus();
 
   if (!consensus)
     return;
@@ -1096,9 +1105,10 @@ routers_update_all_from_networkstatus(time_t now)
   }
 }
 
-/** DOCDOC */
+/** Update v2_download_status_map to contain an entry for every router
+ * descriptor listed in the v2 networkstatuses. */
 static void
-routerstatus_list_update_from_v2_networkstatus(void)
+download_status_map_update_from_v2_networkstatus(void)
 {
   digestmap_t *dl_status;
   if (!networkstatus_v2_list)
@@ -1123,13 +1133,11 @@ routerstatus_list_update_from_v2_networkstatus(void)
   });
   digestmap_free(v2_download_status_map, _tor_free);
   v2_download_status_map = dl_status;
+  networkstatus_v2_list_has_changed = 0;
 }
 
-/** Update our view of router status (as stored in routerstatus_list) from the
- * current set of network status documents (as stored in networkstatus_list).
- * Do nothing unless the network status list has changed since the last time
- * this function was called. DOCDOC
- */
+/** Update our view of the list of named servers from the most recently
+ * retrieved networkstatus consensus */
 static void
 routerstatus_list_update_named_server_map(void)
 {
@@ -1148,9 +1156,9 @@ routerstatus_list_update_named_server_map(void)
     });
 }
 
-/** Given a list <b>routers</b> of routerinfo_t *, update each routers's
- * is_named, is_valid, and is_running fields according to our current
- * networkstatus_t documents.  May re-order <b>router</b>. DOCDOC */
+/** Given a list <b>routers</b> of routerinfo_t *, update each status fields
+ * according to our current consensus networkstatus.  May re-order
+ * <b>router</b>. */
 void
 routers_update_status_from_consensus_networkstatus(smartlist_t *routers,
                                                    int reset_failures)
@@ -1285,7 +1293,7 @@ getinfo_helper_networkstatus(control_connection_t *conn,
   return 0;
 }
 
-/** DOCDOC */
+/** Free all storage held locally in this module. */
 void
 networkstatus_free_all(void)
 {

src/or/routerlist.c

@@ -2101,7 +2101,8 @@ routerlist_free(routerlist_t *rl)
   router_dir_info_changed();
 }
 
-/** DOCDOC */
+/** Log information about how much memory is being used for routerlist,
+ * at log level <b>severity</b>. */
 void
 dump_routerlist_mem_usage(int severity)
 {
@@ -3357,7 +3358,10 @@ any_trusted_dir_is_v1_authority(void)
   return 0;
 }
 
-/** DOCDOC */
+/** For every current directory connection whose purpose is <b>purpose</b>,
+ * and where the resource being downloaded begins with <b>prefix</b>, split
+ * rest of the resource into base16 fingerprints, decode them, and set the
+ * corresponding elements of <b>result</b> to a nonzero value. */
 static void
 list_pending_downloads(digestmap_t *result,
                        int purpose, const char *prefix)
@@ -3490,7 +3494,9 @@ client_would_use_router(routerstatus_t *rs, time_t now, or_options_t *options)
  * them until they have more, or until this amount of time has passed. */
 #define MAX_CLIENT_INTERVAL_WITHOUT_REQUEST (10*60)
 
-/** DOCDOC */
+/** Given a list of router descriptor digests in <b>downloadable</b>, decide
+ * whether to delay fetching until we have more.  If we don't want to delay,
+ * launch one or more requests to the appropriate directory authorities. */
 static void
 launch_router_descriptor_downloads(smartlist_t *downloadable, time_t now)
 {
@@ -3691,7 +3697,8 @@ update_router_descriptor_cache_downloads(time_t now)
   digestmap_free(map,NULL);
 }
 
-/** DOCDOC */
+/** For any descriptor that we want that's currently listed in the live
+ * consensus, download it as appropriate. */
 static void
 update_consensus_router_descriptor_downloads(time_t now)
 {
@@ -3721,10 +3728,9 @@ update_consensus_router_descriptor_downloads(time_t now)
       }
       if (!download_status_is_ready(&rs->dl_status, now,
                                     MAX_ROUTERDESC_DOWNLOAD_FAILURES)) {
-        ++n_delayed;
+        ++n_delayed; /* Not ready for retry. */
         continue;
       }
-
       if (authdir && dirserv_would_reject_router(rs)) {
         ++n_would_reject;
         continue; /* We would throw it out immediately. */