More documenting

svn:r4842

src/or/dirserv.c

@@ -866,7 +866,10 @@ dirserv_set_cached_directory(const char *directory, time_t published,
   }
 }
 
-/** Called when we've just received a DOCDOC */
+/** 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.
+ */
 void
 dirserv_set_cached_networkstatus_v2(const char *directory, const char *fp,
                                     time_t published)
@@ -896,6 +899,14 @@ dirserv_set_cached_networkstatus_v2(const char *directory, const char *fp,
   }
 }
 
+
+/** Helper: If we're authoritative and <b>auth_src</b> is set, use
+ * <b>auth_src</b>, otherwise use <b>cache_src</b>.  If we're using
+ * <b>auth_src</b> and it's been <b>dirty</b> for at least
+ * 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>. */
 static size_t
 dirserv_get_obj(const char **out, int compress,
                 cached_dir_t *cache_src,
@@ -970,6 +981,7 @@ dirserv_regenerate_directory(void)
   return 0;
 }
 
+/** For authoritative directories: the current (v1) network status */
 static cached_dir_t the_runningrouters = { NULL, NULL, 0, 0, 0 };
 
 /** Replace the current running-routers list with a newly generated one. */
@@ -1043,7 +1055,7 @@ dirserv_get_runningrouters(const char **rr, int compress)
                          "v1 network status list");
 }
 
-/** DOCDOC */
+/** Return true iff <b>ri</b> is "useful as an exit node." */
 static int
 router_is_general_exit(routerinfo_t *ri)
 {
@@ -1068,8 +1080,12 @@ router_is_general_exit(routerinfo_t *ri)
   return n_allowed > 0;
 }
 
+/** For authoritative directories: the current (v2) network status */
 static cached_dir_t the_v2_networkstatus = { NULL, NULL, 0, 0, 0 };
 
+/** For authoritative directories only: replace the contents of
+ * <b>the_v2_networkstatus</b> with a newly generated network status
+ * object. */
 static int
 generate_v2_networkstatus(void)
 {
@@ -1225,6 +1241,15 @@ generate_v2_networkstatus(void)
   return r;
 }
 
+/** Look for a network status object as specified by <b>key</b>, which should
+ * be eiher "authority" (to find a network status generated by us), a hex
+ * identity digest (to find a network status generated by given directory), or
+ * "all" (to return all the v2 network status objects we have, concatenated.
+ * If <b>compress</b>, find the version compressed with zlib.  Return 0 if
+ * nothing was found; otherwise set *<b>directory</b> to the matching network
+ * status and return its length.
+ */
+If an appropriate network*/
 size_t
 dirserv_get_networkstatus_v2(const char **directory, const char *key,
                              int compress)
@@ -1250,6 +1275,13 @@ dirserv_get_networkstatus_v2(const char **directory, const char *key,
   return 0;
 }
 
+/**
+ * Add a routerinfo_t to <b>descs_out</b> for each routers matching
+ * <b>key</b>.  The key should be either "/tor/server/authority" for our own
+ * routerinfo; "/tor/server/all" for all the routerinfos we have,
+ * concatenated; or "/tor/server/FP" where FP is a plus-separated sequence of
+ * hex identity digests.
+ */
 void
 dirserv_get_routerdescs(smartlist_t *descs_out, const char *key)
 {