[or-cvs] r17731: {tor} Documentation and conformance for WRA_* returns. shahn: "Add (tor/trunk/src/or)

[nickm@xxxxxxxx]

Author: nickm
Date: 2008-12-22 11:37:20 -0500 (Mon, 22 Dec 2008)
New Revision: 17731

Modified:
   tor/trunk/src/or/dirserv.c
   tor/trunk/src/or/or.h
   tor/trunk/src/or/routerlist.c
Log:
Documentation and conformance for WRA_* returns.

shahn: "Add some documentation for the WRA_* family of functions, also make
sure that (hopefully) all functions that return was_router_added_t
don't return ints directly and that they don't refer to integers in
their documentation anymore."

Modified: tor/trunk/src/or/dirserv.c
===================================================================
--- tor/trunk/src/or/dirserv.c	2008-12-22 16:22:04 UTC (rev 17730)
+++ tor/trunk/src/or/dirserv.c	2008-12-22 16:37:20 UTC (rev 17731)
@@ -653,13 +653,8 @@
  * the list of server descriptors. Set *<b>msg</b> to a message that should be
  * passed back to the origin of this descriptor.
  *
-
- * Return 2 if descriptor is well-formed and accepted;
- *  1 if well-formed and accepted but origin should hear *msg;
- *  0 if well-formed but redundant with one we already have;
- * -1 if it is rejected and origin should hear *msg;
+ * Return the status of the operation
  *
-
  * This function is only called when fresh descriptors are posted, not when
  * we re-load the cache.
  */
@@ -684,7 +679,7 @@
                ri->cache_info.signed_descriptor_body,
                ri->cache_info.signed_descriptor_len, *msg);
     routerinfo_free(ri);
-    return -1;
+    return ROUTER_AUTHDIR_REJECTS;
   }
 
   /* Check whether this descriptor is semantically identical to the last one
@@ -704,7 +699,7 @@
                          ri->cache_info.signed_descriptor_body,
                          ri->cache_info.signed_descriptor_len, *msg);
     routerinfo_free(ri);
-    return 0;
+    return ROUTER_WAS_NOT_NEW;
   }
   if (control_event_is_interesting(EVENT_AUTHDIR_NEWDESCS)) {
     /* Make a copy of desc, since router_add_to_routerlist might free

Modified: tor/trunk/src/or/or.h
===================================================================
--- tor/trunk/src/or/or.h	2008-12-22 16:22:04 UTC (rev 17730)
+++ tor/trunk/src/or/or.h	2008-12-22 16:37:20 UTC (rev 17731)
@@ -4385,19 +4385,25 @@
 static int WRA_WAS_ADDED(was_router_added_t s);
 static int WRA_WAS_OUTDATED(was_router_added_t s);
 static int WRA_WAS_REJECTED(was_router_added_t s);
-/**DOCDOC*/
+/** Return true iff the descriptor was added. It might still be necessary to
+ * check whether the descriptor generator should be notified.
+ */
 static INLINE int
 WRA_WAS_ADDED(was_router_added_t s) {
   return s == ROUTER_ADDED_SUCCESSFULLY || s == ROUTER_ADDED_NOTIFY_GENERATOR;
 }
-/**DOCDOC*/
+/** Return true iff the descriptor was not added because it was either:
+ * - not in the consensus
+ * - neither in the consensus nor in any networkstatus document
+ * - it was outdated.
+ */
 static INLINE int WRA_WAS_OUTDATED(was_router_added_t s)
 {
   return (s == ROUTER_WAS_NOT_NEW ||
           s == ROUTER_NOT_IN_CONSENSUS ||
           s == ROUTER_NOT_IN_CONSENSUS_OR_NETWORKSTATUS);
 }
-/**DOCDOC*/
+/** Return true iff the descriptor rejected because it was malformed. */
 static INLINE int WRA_WAS_REJECTED(was_router_added_t s)
 {
   return (s == ROUTER_AUTHDIR_REJECTS);

Modified: tor/trunk/src/or/routerlist.c
===================================================================
--- tor/trunk/src/or/routerlist.c	2008-12-22 16:22:04 UTC (rev 17730)
+++ tor/trunk/src/or/routerlist.c	2008-12-22 16:37:20 UTC (rev 17731)
@@ -2904,17 +2904,8 @@
  * <b>router</b> after subsequent calls with other routerinfo's -- they
  * might cause the original routerinfo to get freed.
  *
- * Returns >= 0 if the router was added; less than 0 if it was not.
+ * Returns the status for the operation.
  *
- * If we're returning non-zero, then assign to *<b>msg</b> a static string
- * describing the reason for not liking the routerinfo.
- *
- * If the return value is less than -1, there was a problem with the
- * routerinfo. If the return value is equal to -1, then the routerinfo was
- * fine, but out-of-date. If the return value is equal to 1, the
- * routerinfo was accepted, but we should notify the generator of the
- * descriptor using the message *<b>msg</b>.
- *
  * If <b>from_cache</b>, this descriptor came from our disk cache. If
  * <b>from_fetch</b>, we received it in response to a request we made.
  * (If both are false, that means it was uploaded to us as an auth dir
@@ -3068,8 +3059,8 @@
 }
 
 /** Insert <b>ei</b> into the routerlist, or free it. Other arguments are
- * as for router_add_to_routerlist().  Return true iff we actually inserted
- * it.
+ * as for router_add_to_routerlist().  Return ROUTER_ADDED_SUCCESSFULLY iff
+ * we actually inserted it, ROUTER_BAD_EI otherwise.
  */
 was_router_added_t
 router_add_extrainfo_to_routerlist(extrainfo_t *ei, const char **msg,