Resolve all DOCDOCs.

svn:r2050

doc/TODO

@@ -55,7 +55,7 @@ NICK      - Possible to get autoconf to easily install things into ~/.tor?
             to search by digest when appropriate.
           o make sure to use addr/port in cpuworker tasks, because
             OPs don't have keys.
-NICK      - and fix the function comments in rephist
+          o and fix the function comments in rephist
           o Rep-hist functions need to store info by keyid
           - also use this in intro points and rendezvous points, and
             hidserv descs.  [XXXX This isn't enough.]

src/common/util.c

@@ -1458,6 +1458,7 @@ try_next_line:
 char *expand_filename(const char *filename)
 {
   tor_assert(filename);
+  /* XXXX Should eventually check for ~username/ */
   if (!strncmp(filename,"~/",2)) {
     const char *home = getenv("HOME");
     char *result;

src/or/or.h

@@ -603,9 +603,10 @@ typedef struct {
   char *signing_router;
 } routerlist_t;
 
-/* DOCDOC */
+/** Contents of a running-routers list */
 typedef struct running_routers_t {
-  time_t published_on;
+  time_t published_on; /**< When was the list marked as published? */
+  /** Which ORs are on the list?  Entries may be prefixed with ! and $. */
   smartlist_t *running_routers;
 } running_routers_t;
 

src/or/rephist.c

@@ -7,8 +7,6 @@
  * \brief Basic history functionality for reputation module.
  **/
 
-/* DOCDOC references to 'nicknames' in docs here are mostly wrong. */
-
 #include "or.h"
 
 /** History of an OR-\>OR link. */
@@ -39,12 +37,12 @@ typedef struct or_history_t {
   time_t up_since;
   /** If nonzero, we have been unable to connect since this time. */
   time_t down_since;
-  /** Map from lowercased OR2 name to a link_history_t for the link
+  /** Map from hex OR2 identity digest to a link_history_t for the link
    * from this OR to OR2. */
   strmap_t *link_history_map;
 } or_history_t;
 
-/** Map from lowercased OR nickname to or_history_t. */
+/** Map from hex OR identity digest to or_history_t. */
 static strmap_t *history_map = NULL;
 
 /** Return the or_history_t for the named OR, creating it if necessary.
@@ -66,7 +64,8 @@ static or_history_t *get_or_history(const char* id)
 }
 
 /** Return the link_history_t for the link from the first named OR to
- * the second, creating it if necessary.
+ * the second, creating it if necessary. (ORs are identified by
+ * identity digest)
  */
 static link_history_t *get_link_history(const char *from_id,
                                         const char *to_id)
@@ -108,8 +107,8 @@ void rep_hist_init(void)
   history_map = strmap_new();
 }
 
-/** Remember that an attempt to connect to the OR <b>nickname</b> failed at
+/** Remember that an attempt to connect to the OR with identity digest
- * <b>when</b>.
+ * <b>id</b> failed at <b>when</b>.
  */
 void rep_hist_note_connect_failed(const char* id, time_t when)
 {
@@ -124,8 +123,8 @@ void rep_hist_note_connect_failed(const char* id, time_t when)
     hist->down_since = when;
 }
 
-/** Remember that an attempt to connect to the OR <b>nickname</b> succeeded
+/** Remember that an attempt to connect to the OR with identity digest
- * at <b>when</b>.
+ * <b>id</b> succeeded at <b>when</b>.
  */
 void rep_hist_note_connect_succeeded(const char* id, time_t when)
 {
@@ -141,7 +140,7 @@ void rep_hist_note_connect_succeeded(const char* id, time_t when)
 }
 
 /** Remember that we intentionally closed our connection to the OR
- * <b>nickname</b> at <b>when</b>.
+ * with identity digest <b>id</b> at <b>when</b>.
  */
 void rep_hist_note_disconnect(const char* id, time_t when)
 {
@@ -154,8 +153,8 @@ void rep_hist_note_disconnect(const char* id, time_t when)
   }
 }
 
-/** Remember that our connection to the OR <b>id</b> had an error and
+/** Remember that our connection to the OR with identity digest
- * stopped working at <b>when</b>.
+ * <b>id</b> had an error and stopped working at <b>when</b>.
  */
 void rep_hist_note_connection_died(const char* id, time_t when)
 {
@@ -177,8 +176,9 @@ void rep_hist_note_connection_died(const char* id, time_t when)
     hist->down_since = when;
 }
 
-/** Remember that we successfully extended from the OR <b>from_name</b> to
+/** Remember that we successfully extended from the OR with identity
- * the OR <b>to_name</b>.
+ * digest <b>from_id</b> to the OR with identity digest
+ *  <b>to_name</b>.
  */
 void rep_hist_note_extend_succeeded(const char *from_id,
                                     const char *to_id)
@@ -189,8 +189,9 @@ void rep_hist_note_extend_succeeded(const char *from_id,
   ++hist->n_extend_ok;
 }
 
-/** Remember that we tried to extend from the OR <b>from_name</b> to the OR
+/** Remember that we tried to extend from the OR with identity digest
- * <b>to_name</b>, but failed.
+ * <b>from_id</b> to the OR with identity digest <b>to_name</b>, but
+ * failed.
  */
 void rep_hist_note_extend_failed(const char *from_id, const char *to_id)
 {

src/or/routerlist.c

@@ -228,7 +228,10 @@ routerinfo_t *router_get_by_addr_port(uint32_t addr, uint16_t port) {
   return NULL;
 }
 
-/* DOCDOC */
+/** Return true iff the digest of <b>router</b>'s identity key,
+ * encoded in hexadecimal, matches <b>hexdigest</b> (which is
+ * optionally prefixed with a single dollar sign).  Return false if
+ * <b>hexdigest</b> is malformed, or it doesn't match.  */
 static INLINE int router_hex_digest_matches(routerinfo_t *router,
                                      const char *hexdigest)
 {
@@ -237,13 +240,17 @@ static INLINE int router_hex_digest_matches(routerinfo_t *router,
   if (hexdigest[0] == '$')
     ++hexdigest;
 
-  if (base16_decode(digest, DIGEST_LEN, hexdigest, HEX_DIGEST_LEN)<0)
+  if (strlen(hexdigest) != HEX_DIGEST_LEN ||
+      base16_decode(digest, DIGEST_LEN, hexdigest, HEX_DIGEST_LEN)<0)
     return 0;
   else
     return (!memcmp(digest, router->identity_digest, DIGEST_LEN));
 }
 
-/* DOCDOC */
+/* Return true if <b>router</b>'s nickname matches <b>nickname</b>
+ * (case-insensitive), or if <b>router's</b> identity key digest
+ * matches a hexadecimal value stored in <b>nickname</b>.  Return
+ * false otherwise.*/
 int router_nickname_matches(routerinfo_t *router, const char *nickname)
 {
   if (nickname[0]!='$' && !strcasecmp(router->nickname, nickname))
@@ -720,7 +727,7 @@ int router_exit_policy_rejects_all(routerinfo_t *router) {
     == ADDR_POLICY_REJECTED;
 }
 
-/* DODCDOC */
+/* Release all space held in <b>rr</b>. */
 void running_routers_free(running_routers_t *rr)
 {
   tor_assert(rr);
@@ -731,7 +738,8 @@ void running_routers_free(running_routers_t *rr)
   tor_free(rr);
 }
 
-/* DOCDOC*/
+/* Update the running/not-running status of every router in <b>list</b>, based
+ * on the contents of <b>rr</b>. */
 void routerlist_update_from_runningrouters(routerlist_t *list,
                                            running_routers_t *rr)
 {

src/or/routerparse.c

@@ -153,7 +153,9 @@ int router_get_router_hash(const char *s, char *digest)
                               "router ","router-signature");
 }
 
-/** DOCDOC */
+/** Set <b>digest</b> to the SHA-1 digest of the hash of the running-routers
+ * string in <b>s</b>. Return 0 on success, nonzero on failure.
+ */
 int router_get_runningrouters_hash(const char *s, char *digest)
 {
   return router_get_hash_impl(s,digest,