r9715@catbus: nickm | 2007-01-22 02:51:04 -0500

 Document a few undocumented functions and arguments.


svn:r9385

src/or/hibernate.c

@@ -940,7 +940,11 @@ consider_hibernation(time_t now)
   }
 }
 
-/** DOCDOC */
+/** Helper function: called when we get a GETINFO request for an
+ * accounting-related key on the control connection <b>conn</b>.  If we can
+ * answer the request for <b>question</b>, then set *<b>answer</b> to a newly
+ * allocated string holding the result.  Otherwise, set *<b>answer</b> to
+ * NULL. */
 int
 getinfo_helper_accounting(control_connection_t *conn,
                           const char *question, char **answer)

src/or/main.c

@@ -1088,7 +1088,8 @@ ip_address_changed(int at_interface)
   dns_servers_relaunch_checks();
 }
 
-/* DOCDOC */
+/** Forget what we've learned about the correctness of our DNS servers, and
+ * start learning again. */
 void
 dns_servers_relaunch_checks(void)
 {
@@ -2285,7 +2286,9 @@ _tor_dmalloc_free(void *p)
 }
 #endif
 
-/** DOCDOC */
+/** Main entry point for the Tor process.  Called from main(). */
+/* This function is distinct from main() only so we can link main.c into
+ * the unittest binary without conflicting with the unittests' main. */
 int
 tor_main(int argc, char *argv[])
 {

src/or/or.h

@@ -916,8 +916,23 @@ typedef struct cached_dir_t {
   int refcnt; /**< Reference count for this cached_dir_t. */
 } cached_dir_t;
 
+/** Enum used to remember where a signed_descriptor_t is stored and how to
+ * manage the memory for signed_descriptor_body.  */
 typedef enum {
-   SAVED_NOWHERE=0, SAVED_IN_CACHE, SAVED_IN_JOURNAL
+  /** The descriptor isn't stored on disk at all: the copy in memory is
+   * canonical; the saved_offset field is meaningless. */
+  SAVED_NOWHERE=0,
+  /** The descriptor is stored in the cached_routers file: the
+   * signed_descriptor_body is meaningless; the signed_descriptor_len and
+   * saved_offset are used to index into the mmaped cache file. */
+  SAVED_IN_CACHE,
+  /** The descriptor is stored in the cached_routers.new file: the
+   * signed_descriptor_body and saved_offset fields are both set. */
+  /* FFFF (We could also mmap the file and grow the mmap as needed, or
+   * lazy-load the descriptor text by using seek and read.  We don't, for
+   * now.)
+   */
+  SAVED_IN_JOURNAL
 } saved_location_t;
 
 /** Information need to cache an onion router's descriptor. */

src/or/router.c

@@ -381,7 +381,7 @@ static int can_reach_or_port = 0;
 /** Whether we can reach our DirPort from the outside. */
 static int can_reach_dir_port = 0;
 
-/** DOCDOC */
+/** Forget what we have learned about our reachability status. */
 void
 router_reset_reachability(void)
 {
@@ -769,7 +769,8 @@ router_get_my_descriptor(void)
   return body;
 }
 
-/*DOCDOC*/
+/** A list of nicknames that we've warned about including in our family
+ * declaration verbatim rather than as digests. */
 static smartlist_t *warned_nonexistent_family = NULL;
 
 static int router_guess_address_from_dir_headers(uint32_t *guess);
@@ -1315,7 +1316,13 @@ is_legal_hexdigest(const char *s)
           strspn(s,HEX_CHARACTERS)==HEX_DIGEST_LEN);
 }
 
-/** DOCDOC buf must have MAX_VERBOSE_NICKNAME_LEN+1 bytes. */
+/** Set <b>buf</b> (which must have MAX_VERBOSE_NICKNAME_LEN+1 bytes) to the
+ * verbose representation of the identity of <b>router</b>.  The format is:
+ *  A dollar sign.
+ *  The upper-case hexadecimal encoding of the SHA1 hash of router's identity.
+ *  A "=" if the router is named; a "~" if it is not.
+ *  The router's nickname.
+ **/
 void
 router_get_verbose_nickname(char *buf, routerinfo_t *router)
 {

src/or/routerlist.c

@@ -186,7 +186,8 @@ router_should_rebuild_store(void)
 }
 
 /** Add the <b>len</b>-type router descriptor in <b>s</b> to the router
- * journal. */
+ * journal; change its saved_locatino to SAVED_IN_JOURNAL and set its
+ * offset appropriately. */
 static int
 router_append_to_journal(signed_descriptor_t *desc)
 {
@@ -1316,7 +1317,9 @@ router_get_by_descriptor_digest(const char *digest)
   return digestmap_get(routerlist->desc_digest_map, digest);
 }
 
-/* DOCDOC Not always nul-terminated. */
+/** Return a pointer to the signed textual representation of a descriptor.
+ * The returned string is not guaranteed to be NUL-terminated: the string's
+ * length will be in desc->signed_descriptor_len. */
 const char *
 signed_descriptor_get_body(signed_descriptor_t *desc)
 {
@@ -2146,14 +2149,14 @@ router_load_single_router(const char *s, uint8_t purpose, const char **msg)
 }
 
 /** 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
- * are in response to a query to the network: cache them.
+ * routers into our directory.  If saved_location is SAVED_NOWHERE, the routers
+ * are in response to a query to the network: cache them by adding them to
+ * the journal.
  *
  * 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.
- * DOCDOC saved_location
  */
 void
 router_load_routers_from_string(const char *s, saved_location_t saved_location,
@@ -3975,9 +3978,9 @@ router_have_minimum_dir_info(void)
   return have_min_dir_info;
 }
 
-/** DOCDOC
- * Must change when authorities change, networkstatuses change, or list of
- * routerdescs changes, or number of running routers changes.
+/** Called when our internal view of the directory has changed.  This can be
+ * when the authorities change, networkstatuses change, the list of routerdescs
+ * changes, or number of running routers changes.
  */
 static void
 router_dir_info_changed(void)
@@ -3985,7 +3988,9 @@ router_dir_info_changed(void)
   need_to_update_have_min_dir_info = 1;
 }
 
-/** DOCDOC */
+/** Change the value of have_min_dir_info, setting it true iff we have enough
+ * network and router information to build circuits.  Clear the value of
+ * need_to_update_have_min_dir_info. */
 static void
 update_router_have_minimum_dir_info(void)
 {
@@ -4251,7 +4256,8 @@ getinfo_helper_networkstatus(control_connection_t *conn,
   return 0;
 }
 
-/*DOCDOC*/
+/** Assert that the internal representation of <b>rl</b> is
+ * self-consistent. */
 static void
 routerlist_assert_ok(routerlist_t *rl)
 {

src/or/routerparse.c

@@ -632,8 +632,13 @@ check_directory_signature(const char *digest,
  * descriptors, parses them and stores the result in <b>dest</b>.  All routers
  * are marked running and valid.  Advances *s to a point immediately
  * following the last router entry.  Ignore any trailing router entries that
- * are not complete. Returns 0 on success and -1 on failure.
- * DOCDOC saved_location
+ * are not complete.
+ *
+ * If <b>saved_location</b> isn't SAVED_IN_CACHE, make a local copy of each
+ * descriptor in the signed_descriptor_body field of each routerinfo_t.  If it
+ * isn't SAVED_NOWHERE, remember the offset of each descriptor.
+ *
+ * Returns 0 on success and -1 on failure.
  */
 int
 router_parse_list_from_string(const char **s, smartlist_t *dest,
@@ -719,8 +724,9 @@ dump_distinct_digest_count(int severity)
 
 /** Helper function: reads a single router entry from *<b>s</b> ...
  * *<b>end</b>.  Mallocs a new router and returns it if all goes well, else
- * returns NULL.
- * DOCDOC cache_copy
+ * returns NULL.  If <b>cache_copy</b> is true, duplicate the contents of
+ * s through end into the signed_descriptor_body of the resulting
+ * routerinfo_t.
  */
 routerinfo_t *
 router_parse_entry_from_string(const char *s, const char *end,