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."

svn:r17731

src/or/dirserv.c

@@ -653,13 +653,8 @@ dirserv_add_multiple_descriptors(const char *desc, uint8_t purpose,
  * 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 @@ dirserv_add_descriptor(routerinfo_t *ri, const char **msg)
                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 @@ dirserv_add_descriptor(routerinfo_t *ri, const char **msg)
                          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

src/or/or.h

@@ -4385,19 +4385,25 @@ typedef enum was_router_added_t {
 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);

src/or/routerlist.c

@@ -2904,16 +2904,7 @@ router_set_status(const char *digest, int up)
  * <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.
- *
- * 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>.
+ * Returns the status for the operation.
  *
  * 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.
@@ -3068,8 +3059,8 @@ router_add_to_routerlist(routerinfo_t *router, const char **msg,
 }
 
 /** 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,