From 167d266dbf618c856a87ac482668cd848651ab62 Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Mon, 22 Dec 2008 16:37:20 +0000 Subject: [PATCH] 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 | 11 +++-------- src/or/or.h | 12 +++++++++--- src/or/routerlist.c | 15 +++------------ 3 files changed, 15 insertions(+), 23 deletions(-) diff --git a/src/or/dirserv.c b/src/or/dirserv.c index 914fcc2f49..3fd6b7a566 100644 --- a/src/or/dirserv.c +++ b/src/or/dirserv.c @@ -653,13 +653,8 @@ dirserv_add_multiple_descriptors(const char *desc, uint8_t purpose, * the list of server descriptors. Set *msg 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 diff --git a/src/or/or.h b/src/or/or.h index ffb9894438..ff578b0b4b 100644 --- a/src/or/or.h +++ b/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); diff --git a/src/or/routerlist.c b/src/or/routerlist.c index 020061925b..78c02ddb24 100644 --- a/src/or/routerlist.c +++ b/src/or/routerlist.c @@ -2904,16 +2904,7 @@ router_set_status(const char *digest, int up) * router 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 *msg 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 *msg. + * Returns the status for the operation. * * If from_cache, this descriptor came from our disk cache. If * from_fetch, 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 ei 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, -- 2.11.4.GIT