[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]
[or-cvs] Resolve all DOCDOCs.
Update of /home/or/cvsroot/src/or
In directory moria.mit.edu:/tmp/cvs-serv4571/src/or
Modified Files:
or.h rephist.c routerlist.c routerparse.c
Log Message:
Resolve all DOCDOCs.
Index: or.h
===================================================================
RCS file: /home/or/cvsroot/src/or/or.h,v
retrieving revision 1.379
retrieving revision 1.380
diff -u -d -r1.379 -r1.380
--- or.h 13 Jul 2004 19:16:49 -0000 1.379
+++ or.h 16 Jul 2004 22:23:18 -0000 1.380
@@ -603,9 +603,10 @@
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;
Index: rephist.c
===================================================================
RCS file: /home/or/cvsroot/src/or/rephist.c,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -d -r1.13 -r1.14
--- rephist.c 13 Jul 2004 18:23:40 -0000 1.13
+++ rephist.c 16 Jul 2004 22:23:18 -0000 1.14
@@ -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 @@
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 @@
}
/** 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 @@
history_map = strmap_new();
}
-/** Remember that an attempt to connect to the OR <b>nickname</b> failed at
- * <b>when</b>.
+/** Remember that an attempt to connect to the OR with identity digest
+ * <b>id</b> failed at <b>when</b>.
*/
void rep_hist_note_connect_failed(const char* id, time_t when)
{
@@ -124,8 +123,8 @@
hist->down_since = when;
}
-/** Remember that an attempt to connect to the OR <b>nickname</b> succeeded
- * at <b>when</b>.
+/** Remember that an attempt to connect to the OR with identity digest
+ * <b>id</b> succeeded at <b>when</b>.
*/
void rep_hist_note_connect_succeeded(const char* id, time_t when)
{
@@ -141,7 +140,7 @@
}
/** 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 @@
}
}
-/** Remember that our connection to the OR <b>id</b> had an error and
- * stopped working at <b>when</b>.
+/** Remember that our connection to the OR with identity digest
+ * <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 @@
hist->down_since = when;
}
-/** Remember that we successfully extended from the OR <b>from_name</b> to
- * the OR <b>to_name</b>.
+/** Remember that we successfully extended from the OR with identity
+ * 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 @@
++hist->n_extend_ok;
}
-/** Remember that we tried to extend from the OR <b>from_name</b> to the OR
- * <b>to_name</b>, but failed.
+/** Remember that we tried to extend from the OR with identity digest
+ * <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)
{
Index: routerlist.c
===================================================================
RCS file: /home/or/cvsroot/src/or/routerlist.c,v
retrieving revision 1.96
retrieving revision 1.97
diff -u -d -r1.96 -r1.97
--- routerlist.c 12 Jul 2004 20:39:40 -0000 1.96
+++ routerlist.c 16 Jul 2004 22:23:18 -0000 1.97
@@ -228,7 +228,10 @@
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 @@
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 @@
== 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 @@
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)
{
Index: routerparse.c
===================================================================
RCS file: /home/or/cvsroot/src/or/routerparse.c,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -d -r1.11 -r1.12
--- routerparse.c 13 Jul 2004 19:16:49 -0000 1.11
+++ routerparse.c 16 Jul 2004 22:23:18 -0000 1.12
@@ -153,7 +153,9 @@
"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,