And some documentation before bed.

svn:r5073

3 files changed, 42 insertions, 16 deletions

diff --git a/src/or/directory.c b/src/or/directory.c
index fe05d6541..6901a1719 100644
--- a/src/or/directory.c
+++ b/src/or/directory.c
@@ -1557,7 +1557,7 @@ connection_dir_finished_connecting(connection_t *conn)
 }
 
 /** Called when one or more networkstatus fetches have failed (with uppercase
- * fingerprints listed in <b>fp</>).  Mark those fingerprints has having
+ * fingerprints listed in <b>failed</>).  Mark those fingerprints has having
  * failed once. */
 static void
 dir_networkstatus_download_failed(smartlist_t *failed)
@@ -1573,7 +1573,8 @@ dir_networkstatus_download_failed(smartlist_t *failed)
   });
 }
 
-/* DOCDOC */
+/** Called when one or more networkstatus fetches have failed (with uppercase
+ * fingerprints listed in <b>failed</>). */
 static void
 dir_routerdesc_download_failed(smartlist_t *failed)
 {
diff --git a/src/or/dirserv.c b/src/or/dirserv.c
index 7c81b6c06..30b1f5b9e 100644
--- a/src/or/dirserv.c
+++ b/src/or/dirserv.c
@@ -165,8 +165,10 @@ dirserv_parse_fingerprint_file(const char *fname)
 
 /** Check whether <b>router</b> has a nickname/identity key combination that
  * we recognize from the fingerprint list, or an IP we automatically act on
- * according to our configuration.  Return the appropriate disposition.
- * DOCDOC msg is set on reject, if provided.
+ * according to our configuration.  Return the appropriate router status.
+ *
+ * If the status is 'FP_REJECT' and <b>msg</b> is provided, set
+ * *<b>msg</b> to an explanation of why.
  */
 static router_status_t
 dirserv_router_get_status(const routerinfo_t *router, const char **msg)
@@ -287,7 +289,8 @@ dirserv_router_has_valid_address(routerinfo_t *ri)
 /** Check whether we, as a directory server, want to accept <b>ri</b>.  If so,
  * return 0, and set its is_valid,named,running fields.  Otherwise, return -1.
  *
- * DOCDOC msg
+ * If the router is rejected and <b>msg</b> is provided, set
+ * *<b>msg</b> to an explanation of why.
  */
 int
 authdir_wants_to_reject_router(routerinfo_t *ri,
@@ -595,7 +598,9 @@ list_server_status(smartlist_t *routers, char **router_status_out)
   return 0;
 }
 
-/* DOCDOC */
+/** Helper: Given pointers to two strings describing tor versions, return -1
+ * if _a precedes _b, 1 if _b preceeds _a, and 0 if they are equivalent.
+ * Used to sort a list of versions. */
 static int
 _compare_tor_version_str_ptr(const void **_a, const void **_b)
 {
@@ -620,7 +625,8 @@ _compare_tor_version_str_ptr(const void **_a, const void **_b)
 /* Given a (possibly empty) list of config_line_t, each line of which contains
  * a list of comma-separated version numbers surrounded by optional space,
  * allocate and return a new string containing the version numbers, in order,
- * separated by commas.  Used to generate Recommended(Client|Server)?Versions */
+ * separated by commas.  Used to generate Recommended(Client|Server)?Versions
+ */
 static char *
 format_versions_list(config_line_t *ln)
 {
diff --git a/src/or/routerlist.c b/src/or/routerlist.c
index 6b4295d4c..ef839711b 100644
--- a/src/or/routerlist.c
+++ b/src/or/routerlist.c
@@ -211,7 +211,9 @@ router_rebuild_store(int force)
   return r;
 }
 
-/* DOCDOC */
+/* Load all cached router descriptors from the store. Return 0 on success and
+ * -1 on failure.
+ */
 int
 router_reload_router_list(void)
 {
@@ -1072,7 +1074,7 @@ router_mark_as_down(const char *digest)
 }
 
 /** Add <b>router</b> to the routerlist, if we don't already have it.  Replace
- * older entries (if any) with the same name.  Note: Callers should not hold
+ * older entries (if any) with the same key.  Note: Callers should not hold
  * their pointers to <b>router</b> if this function fails; <b>router</b>
  * will either be inserted into the routerlist or freed.
  *
@@ -1087,9 +1089,9 @@ router_mark_as_down(const char *digest)
  * routerinfo was accepted, but we should notify the generator of the
  * descriptor using the message *<b>msg</b>.
  *
- * DOCDOC very changed.  Also, MUST call update_status_from_networkstatus
- * first, and should call router_rebuild_store and
- * control_event_descriptors_changed after.
+ * This function should be called *after*
+ * routers_update_status_from_networkstatus; subsequenctly, you should call
+ * router_rebuild_store and control_event_descriptors_changed.
  *
  * XXXX never replace your own descriptor.
  */
@@ -1286,7 +1288,15 @@ router_load_single_router(const char *s, const char **msg)
   return 1;
 }
 
-/* DOCDOC */
+/** Given a string <b>s</b> containing some routerdescs, parse it and put the
+ * routers into our directory.  If <b>from_cache</b> is false, the routers
+ * have come from the network: cache them.
+ *
+ * If <b>requested_fingerprints</b> is provided, it must contain a list of
+ * uppercased identity fingerprints.  Do not update any router whose
+ * fingerprint is not on the list; after updating a router, remove its
+ * fingerprint from the list.
+ */
 void
 router_load_routers_from_string(const char *s, int from_cache,
                                 smartlist_t *requested_fingerprints)
@@ -1422,7 +1432,7 @@ _compare_networkstatus_published_on(const void **_a, const void **_b)
  * fingerprint is not on the list; after updating a networkstatus, remove its
  * fingerprint from the list.
  *
- * Return 0 on success, -1 on failure.
+o * Return 0 on success, -1 on failure.
  */
 int
 router_set_networkstatus(const char *s, time_t arrived_at,
@@ -2402,7 +2412,14 @@ router_list_downloadable(void)
   return superseded;
 }
 
-/* DOCDOC */
+/** Initiate new router downloads as needed.
+ *
+ * We only allow one router descriptor download at a time.
+ * If we have less than two network-status documents, we ask
+ * a directory for "all descriptors."
+ * Otherwise, we ask for all descriptors that we think are different
+ * from what we have.
+ */
 void
 update_router_descriptor_downloads(time_t now)
 {
@@ -2438,7 +2455,9 @@ update_router_descriptor_downloads(time_t now)
   tor_free(resource);
 }
 
-/* DOCDOC */
+/** Return true iff we have enough networkstatus and router information to
+ * start building circuits.  Right now, this means "at least 2 networkstatus
+ * documents, and at least 1/4 of expected routers." */
 int
 router_have_minimum_dir_info(void)
 {