diff options
| -rw-r--r-- | src/or/directory.c | 5 | ||||
| -rw-r--r-- | src/or/dirserv.c | 16 | ||||
| -rw-r--r-- | src/or/routerlist.c | 37 |
3 files changed, 42 insertions, 16 deletions
diff --git a/src/or/directory.c b/src/or/directory.c index fe05d6541..6901a1719 100644 --- a/src/or/directory.c +++ b/src/or/directory.c @@ -1557,7 +1557,7 @@ connection_dir_finished_connecting(connection_t *conn) } /** Called when one or more networkstatus fetches have failed (with uppercase - * fingerprints listed in <b>fp</>). Mark those fingerprints has having + * fingerprints listed in <b>failed</>). Mark those fingerprints has having * failed once. */ static void dir_networkstatus_download_failed(smartlist_t *failed) @@ -1573,7 +1573,8 @@ dir_networkstatus_download_failed(smartlist_t *failed) }); } -/* DOCDOC */ +/** Called when one or more networkstatus fetches have failed (with uppercase + * fingerprints listed in <b>failed</>). */ static void dir_routerdesc_download_failed(smartlist_t *failed) { diff --git a/src/or/dirserv.c b/src/or/dirserv.c index 7c81b6c06..30b1f5b9e 100644 --- a/src/or/dirserv.c +++ b/src/or/dirserv.c @@ -165,8 +165,10 @@ dirserv_parse_fingerprint_file(const char *fname) /** Check whether <b>router</b> has a nickname/identity key combination that * we recognize from the fingerprint list, or an IP we automatically act on - * according to our configuration. Return the appropriate disposition. - * DOCDOC msg is set on reject, if provided. + * according to our configuration. Return the appropriate router status. + * + * If the status is 'FP_REJECT' and <b>msg</b> is provided, set + * *<b>msg</b> to an explanation of why. */ static router_status_t dirserv_router_get_status(const routerinfo_t *router, const char **msg) @@ -287,7 +289,8 @@ dirserv_router_has_valid_address(routerinfo_t *ri) /** Check whether we, as a directory server, want to accept <b>ri</b>. If so, * return 0, and set its is_valid,named,running fields. Otherwise, return -1. * - * DOCDOC msg + * If the router is rejected and <b>msg</b> is provided, set + * *<b>msg</b> to an explanation of why. */ int authdir_wants_to_reject_router(routerinfo_t *ri, @@ -595,7 +598,9 @@ list_server_status(smartlist_t *routers, char **router_status_out) return 0; } -/* DOCDOC */ +/** Helper: Given pointers to two strings describing tor versions, return -1 + * if _a precedes _b, 1 if _b preceeds _a, and 0 if they are equivalent. + * Used to sort a list of versions. */ static int _compare_tor_version_str_ptr(const void **_a, const void **_b) { @@ -620,7 +625,8 @@ _compare_tor_version_str_ptr(const void **_a, const void **_b) /* Given a (possibly empty) list of config_line_t, each line of which contains * a list of comma-separated version numbers surrounded by optional space, * allocate and return a new string containing the version numbers, in order, - * separated by commas. Used to generate Recommended(Client|Server)?Versions */ + * separated by commas. Used to generate Recommended(Client|Server)?Versions + */ static char * format_versions_list(config_line_t *ln) { diff --git a/src/or/routerlist.c b/src/or/routerlist.c index 6b4295d4c..ef839711b 100644 --- a/src/or/routerlist.c +++ b/src/or/routerlist.c @@ -211,7 +211,9 @@ router_rebuild_store(int force) return r; } -/* DOCDOC */ +/* Load all cached router descriptors from the store. Return 0 on success and + * -1 on failure. + */ int router_reload_router_list(void) { @@ -1072,7 +1074,7 @@ router_mark_as_down(const char *digest) } /** Add <b>router</b> to the routerlist, if we don't already have it. Replace - * older entries (if any) with the same name. Note: Callers should not hold + * older entries (if any) with the same key. Note: Callers should not hold * their pointers to <b>router</b> if this function fails; <b>router</b> * will either be inserted into the routerlist or freed. * @@ -1087,9 +1089,9 @@ router_mark_as_down(const char *digest) * routerinfo was accepted, but we should notify the generator of the * descriptor using the message *<b>msg</b>. * - * DOCDOC very changed. Also, MUST call update_status_from_networkstatus - * first, and should call router_rebuild_store and - * control_event_descriptors_changed after. + * This function should be called *after* + * routers_update_status_from_networkstatus; subsequenctly, you should call + * router_rebuild_store and control_event_descriptors_changed. * * XXXX never replace your own descriptor. */ @@ -1286,7 +1288,15 @@ router_load_single_router(const char *s, const char **msg) return 1; } -/* DOCDOC */ +/** Given a string <b>s</b> containing some routerdescs, parse it and put the + * routers into our directory. If <b>from_cache</b> is false, the routers + * have come from the network: cache them. + * + * If <b>requested_fingerprints</b> is provided, it must contain a list of + * uppercased identity fingerprints. Do not update any router whose + * fingerprint is not on the list; after updating a router, remove its + * fingerprint from the list. + */ void router_load_routers_from_string(const char *s, int from_cache, smartlist_t *requested_fingerprints) @@ -1422,7 +1432,7 @@ _compare_networkstatus_published_on(const void **_a, const void **_b) * fingerprint is not on the list; after updating a networkstatus, remove its * fingerprint from the list. * - * Return 0 on success, -1 on failure. +o * Return 0 on success, -1 on failure. */ int router_set_networkstatus(const char *s, time_t arrived_at, @@ -2402,7 +2412,14 @@ router_list_downloadable(void) return superseded; } -/* DOCDOC */ +/** Initiate new router downloads as needed. + * + * We only allow one router descriptor download at a time. + * If we have less than two network-status documents, we ask + * a directory for "all descriptors." + * Otherwise, we ask for all descriptors that we think are different + * from what we have. + */ void update_router_descriptor_downloads(time_t now) { @@ -2438,7 +2455,9 @@ update_router_descriptor_downloads(time_t now) tor_free(resource); } -/* DOCDOC */ +/** Return true iff we have enough networkstatus and router information to + * start building circuits. Right now, this means "at least 2 networkstatus + * documents, and at least 1/4 of expected routers." */ int router_have_minimum_dir_info(void) { |