diff --git a/src/or/circuitlist.c b/src/or/circuitlist.c index 61dca3fbfe..2f01f75fde 100644 --- a/src/or/circuitlist.c +++ b/src/or/circuitlist.c @@ -634,12 +634,10 @@ circuit_get_by_rend_query_and_purpose(const char *rend_query, uint8_t purpose) return NULL; } -/** Return the first circuit in global_circuitlist after start - * whose purpose is purpose is purpose, and (if set) whose - * digest matches the rend_pk_digest field. Return NULL if no - * circuit is found. - * If start is NULL, begin at the start of the list. - * DOCDOC origin. +/** Return the first circuit originating here in global_circuitlist after + * start whose purpose is purpose is purpose, and where + * digest (if set) matches the rend_pk_digest field. Return NULL if no + * circuit is found. If start is NULL, begin at the start of the list. */ origin_circuit_t * circuit_get_next_by_pk_and_purpose(origin_circuit_t *start, @@ -666,7 +664,9 @@ circuit_get_next_by_pk_and_purpose(origin_circuit_t *start, return NULL; } -/* DOCDOC */ +/** Return the first OR circuit in the global list whose purpose is + * purpose, and whose rend_token is the len-byte + * token. */ static or_circuit_t * circuit_get_by_rend_token_and_purpose(uint8_t purpose, const char *token, size_t len) diff --git a/src/or/connection_edge.c b/src/or/connection_edge.c index f82b1bab27..0afe3013c5 100644 --- a/src/or/connection_edge.c +++ b/src/or/connection_edge.c @@ -632,7 +632,8 @@ addressmap_virtaddress_remove(const char *address, addressmap_entry_t *ent) } } -/* DOCDOC */ +/** Remove ent (which must be mapped to by address) from the + * client address maps. */ static void addressmap_ent_remove(const char *address, addressmap_entry_t *ent) { @@ -708,7 +709,9 @@ addressmap_rewrite(char *address, size_t maxlen) /* it's fine to rewrite a rewrite, but don't loop forever */ } -/* DOCDOC */ +/** If we have a cached reverse DNS entry for the address stored in the + * maxlen-byte buffer address (typically, a dotted quad) with + * the cached value and return 1. Otherwise return 0. */ static int addressmap_rewrite_reverse(char *address, size_t maxlen) { @@ -898,7 +901,15 @@ client_dns_set_addressmap(const char *address, uint32_t val, client_dns_set_addressmap_impl(address, valbuf, exitname, ttl); } -/** DOCDOC */ +/** Add a cache entry noting that address (ordinarily a dotted quad) + * resolved via a RESOLVE_PTR request to the hostname v. + * + * If exitname is defined, then append the addresses with + * ".exitname.exit" before registering the mapping. + * + * If ttl is nonnegative, the mapping will be valid for + * ttlseconds; otherwise, we use the default. + */ static void client_dns_set_reverse_addressmap(const char *address, const char *v, const char *exitname, @@ -2003,11 +2014,10 @@ connection_ap_handshake_socks_resolved(edge_connection_t *conn, * socks version, etc, and mark conn as completed with SOCKS * handshaking. * - * If reply is defined, then write replylen bytes of it - * to conn and return, else reply based on status. - * - * If reply is undefined, status can't be 0. - * DOCDOC endreason + * If reply is defined, then write replylen bytes of it to conn + * and return, else reply based on endreason (one of + * END_STREAM_REASON_*). If reply is undefined, endreason can't 0 + * or REASON_DONE. Send endreason to the controller, if appropriate. */ void connection_ap_handshake_socks_reply(edge_connection_t *conn, char *reply, diff --git a/src/or/control.c b/src/or/control.c index be404bfddd..0b34b0d8a6 100644 --- a/src/or/control.c +++ b/src/or/control.c @@ -631,7 +631,13 @@ send_control0_event(uint16_t event, uint32_t len, const char *body) /* Send an event to all v1 controllers that are listening for code * event. The event's body is given by msg. * - * docdoc which, is_extended */ + * If which & SHORT_NAMES, the event contains short-format names: send + * it to controllers that haven't enabled the VERBOSE_NAMES feature. If + * which & LONG_NAMES, the event contains long-format names: sent it + * to contollers that have enabled VERBOSE_NAMES. + * + * The EXTENDED_FORMAT and NONEXTENDED_FORMAT flags behaves similarly with + * respect to the EXTENDED_EVENTS feature. */ static void send_control1_event_string(uint16_t event, event_format_t which, const char *msg) @@ -3118,7 +3124,8 @@ write_stream_target_to_buf(edge_connection_t *conn, char *buf, size_t len) return 0; } -/* DOCDOC */ +/** Convert the reason for ending a stream reason into the format used + * in STREAM events. Return NULL if the reason is unrecognized.*/ static const char * stream_end_reason_to_string(int reason) { @@ -3585,7 +3592,8 @@ control_event_or_authdir_new_descriptor(const char *action, return 0; } -/* DOCDOC takes a list of local_routerstatus_t */ +/** Called when the local_routerstatus_ts statuses have changed: sends + * an NS event to any controller that cares. */ int control_event_networkstatus_changed(smartlist_t *statuses) { @@ -3612,7 +3620,8 @@ control_event_networkstatus_changed(smartlist_t *statuses) return 0; } -/* DOCDOC */ +/** Called when a single local_routerstatus_t has changed: Sends an NS event + * to any countroller that cares. */ int control_event_networkstatus_changed_single(local_routerstatus_t *rs) { @@ -3638,7 +3647,10 @@ control_event_my_descriptor_changed(void) return 0; } -/* DOCDOC */ +/** Helper: sents a status event where type is one of + * EVENT_STATUS_{GENERAL,CLIENT,SERVER}, where severity is one of + * LOG_{NOTICE,WARN,ERR}, and where format is a print-style format + * string corresponding to args. */ static int control_event_status(int type, int severity, const char *format, va_list args) { @@ -3683,7 +3695,8 @@ control_event_status(int type, int severity, const char *format, va_list args) return 0; } -/* DOCDOC */ +/** Format and send an EVENT_STATUS_GENERAL event whose main text is obtained + * by formatting the arguments using the printf-style format */ int control_event_general_status(int severity, const char *format, ...) { @@ -3698,7 +3711,8 @@ control_event_general_status(int severity, const char *format, ...) return r; } -/* DOCDOC */ +/** Format and send an EVENT_STATUS_CLIENT event whose main text is obtained + * by formatting the arguments using the printf-style format */ int control_event_client_status(int severity, const char *format, ...) { @@ -3713,7 +3727,8 @@ control_event_client_status(int severity, const char *format, ...) return r; } -/* DOCDOC */ +/** Format and send an EVENT_STATUS_SERVER event whose main text is obtained + * by formatting the arguments using the printf-style format */ int control_event_server_status(int severity, const char *format, ...) { @@ -3728,7 +3743,9 @@ control_event_server_status(int severity, const char *format, ...) return r; } -/** DOCDOC */ +/** Called when the status of an entry guard with the given nickname + * and identity digest has changed to status: tells any + * controllers that care. */ int control_event_guard(const char *nickname, const char *digest, const char *status) diff --git a/src/or/directory.c b/src/or/directory.c index 87977a9c0d..3db8d938d7 100644 --- a/src/or/directory.c +++ b/src/or/directory.c @@ -1444,10 +1444,13 @@ already_fetching_directory(int purpose) #undef INSTRUMENT_DOWNLOADS #ifdef INSTRUMENT_DOWNLOADS -/** DOCDOC */ +/** Map used to keep track of how much data we've up/downloaded in what kind + * of request. Maps from request type to pointer to uint64_t. */ static strmap_t *request_bytes_map = NULL; -/** DOCDOC */ +/** Called when we just transmitted or received bytes worth of data + * because of a request of type key (an arbitrary identifier): adds + * bytes to the total associated with key. */ static void note_request(const char *key, size_t bytes) { @@ -1463,7 +1466,8 @@ note_request(const char *key, size_t bytes) *n += bytes; } -/** DOCDOC */ +/** Return a newly allocated string holding a summary of bytes used per + * request type. */ char * directory_dump_request_log(void) { diff --git a/src/or/routerlist.c b/src/or/routerlist.c index 132e8339be..3060375e47 100644 --- a/src/or/routerlist.c +++ b/src/or/routerlist.c @@ -906,6 +906,7 @@ router_find_exact_exit_enclave(const char *address, uint16_t port) * If need_uptime is non-zero, we require a minimum uptime. * If need_capacity is non-zero, we require a minimum advertised * bandwidth. + * If need_guard, we require that the router is a possible entry guard. */ int router_is_unreliable(routerinfo_t *router, int need_uptime, @@ -939,7 +940,10 @@ router_get_advertised_bandwidth(routerinfo_t *router) * If statuses is zero, then sl is a list of * routerinfo_t's. Otherwise it's a list of routerstatus_t's. * - * DOCDOC for_exit + * If for_exit, we're picking an exit node: consider all nodes' + * bandwidth equally regardless of their Exit status. If not for_exit, + * we're picking a non-exit node: weight exit-node's bandwidth downwards + * depending on the smallness of the fraction of Exit-to-total bandwidth. */ static void * smartlist_choose_by_bandwidth(smartlist_t *sl, int for_exit, int statuses) @@ -972,6 +976,9 @@ smartlist_choose_by_bandwidth(smartlist_t *sl, int for_exit, int statuses) this_bw = status->is_fast ? 40000 : 20000; else /* assume it'll be the average we've seen so far */ this_bw = (uint32_t)(partial/i); + /*XXXX012 The above calculation is an awful hack, and makes our + * algorithm hard to describe sanely. Could we do better with a second + * pass through the list? -NM */ } } else { router = smartlist_get(sl, i); @@ -1063,8 +1070,11 @@ routerstatus_sl_choose_by_bandwidth(smartlist_t *sl) * a minimum uptime, return one of those. * If need_capacity is non-zero, weight your choice by the * advertised capacity of each router. - * - * DOCDOC allow_invalid, need_guard, weight_for_exit + * If ! allow_invalid, consider only Valid routers. + * If need_guard, consider only Guard routers. + * If weight_for_exit, we weight bandwidths as if picking an exit node, + * otherwise we weight bandwidths for picking a relay node (that is, possibly + * discounting exit nodes). */ routerinfo_t * router_choose_random_node(const char *preferred, @@ -3782,15 +3792,13 @@ router_list_client_downloadable(void) /** Initiate new router downloads as needed, using the strategy for * non-directory-servers. * - * 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. + * We don't launch any downloads if there are fewer than MAX_DL_TO_DELAY + * descriptors to get and less than MAX_CLIENT_INTERVAL_WITHOUT_REQUEST + * seconds have passed. * - * DOCDOC The above comment doesn't match the behavior of the function. - * I guess one of them is wrong, and I guess it's the comment. -RD - */ + * Otherwise, we ask for all descriptors that we think are different from what + * we have, and that we don't currently have an in-progress download attempt + * for. */ static void update_router_descriptor_client_downloads(time_t now) {