From 6693f3253097326abe3a57469690330cd73d2456 Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Wed, 17 Dec 2008 22:58:20 +0000 Subject: [PATCH] Resolve many DOCDOCs. svn:r17662 --- src/common/address.c | 2 +- src/common/log.c | 12 ++++++++---- src/common/memarea.c | 2 +- src/common/tortls.c | 6 +++++- src/common/tortls.h | 3 ++- src/or/config.c | 3 ++- src/or/connection_edge.c | 7 +++++-- src/or/directory.c | 17 +++++++++++------ src/or/dns.c | 3 ++- src/or/eventdns.c | 2 +- src/or/geoip.c | 17 ++++++++++++----- src/or/relay.c | 13 +++++++++++-- src/or/rephist.c | 12 +++++++++--- src/or/routerlist.c | 38 ++++++++++++++++++++++++++------------ 14 files changed, 96 insertions(+), 41 deletions(-) diff --git a/src/common/address.c b/src/common/address.c index d6b64828c1..7da9cb220b 100644 --- a/src/common/address.c +++ b/src/common/address.c @@ -630,7 +630,7 @@ tor_addr_from_ipv6_bytes(tor_addr_t *dest, const char *ipv6_bytes) memcpy(dest->addr.in6_addr.s6_addr, ipv6_bytes, 16); } -/** DOCDOC */ +/** Set dest equal to the IPv6 address in the in6_addr in6. */ void tor_addr_from_in6(tor_addr_t *dest, const struct in6_addr *in6) { diff --git a/src/common/log.c b/src/common/log.c index dca7866273..d93bc8a556 100644 --- a/src/common/log.c +++ b/src/common/log.c @@ -53,7 +53,8 @@ typedef struct logfile_t { int is_temporary; /**< Boolean: close after initializing logging subsystem.*/ int is_syslog; /**< Boolean: send messages to syslog. */ log_callback callback; /**< If not NULL, send messages to this function. */ - log_severity_list_t *severities; /**< DOCDOC */ + log_severity_list_t *severities; /**< Which severity of messages should we + * log for each log domain? */ } logfile_t; static void log_free(logfile_t *victim); @@ -415,7 +416,7 @@ _log_err(log_domain_mask_t domain, const char *format, ...) } #endif -/** DOCDOC */ +/** Free all storage held by victim. */ static void log_free(logfile_t *victim) { @@ -730,14 +731,17 @@ log_level_to_string(int level) return sev_to_string(level); } -/** DOCDOC */ +/** NULL-terminated array of names for log domains such that domain_list[dom] + * is a description of dom. */ static const char *domain_list[] = { "GENERAL", "CRYPTO", "NET", "CONFIG", "FS", "PROTOCOL", "MM", "HTTP", "APP", "CONTROL", "CIRC", "REND", "BUG", "DIR", "DIRSERV", "OR", "EDGE", "ACCT", "HIST", NULL }; -/** DOCDOC */ +/** Return the log domain for which domain is the name, or 0 if there + * is no such name. */ +/*XXXX021 0 could mean "no such domain" or LD_GENERAL. Fix that. */ static log_domain_mask_t parse_log_domain(const char *domain) { diff --git a/src/common/memarea.c b/src/common/memarea.c index d888cf076a..4257c4552c 100644 --- a/src/common/memarea.c +++ b/src/common/memarea.c @@ -138,7 +138,7 @@ memarea_clear(memarea_t *area) area->first->next_mem = area->first->u.mem; } -/** DOCDOC */ +/** Remove all unused memarea chunks from the internal freelist. */ void memarea_clear_freelist(void) { diff --git a/src/common/tortls.c b/src/common/tortls.c index 1032a53f25..ec59d67ae6 100644 --- a/src/common/tortls.c +++ b/src/common/tortls.c @@ -1442,7 +1442,11 @@ tor_tls_used_v1_handshake(tor_tls_t *tls) return 1; } -/** DOCDOC */ +/** Examine the amount of memory used and available for buffers in tls. + * Set *rbuf_capacity to the amount of storage allocated for the read + * buffer and *rbuf_bytes to the amount actually used. + * Set *wbuf_capacity to the amount of storage allocated for the write + * buffer and *wbuf_bytes to the amount actually used. */ void tor_tls_get_buffer_sizes(tor_tls_t *tls, int *rbuf_capacity, int *rbuf_bytes, diff --git a/src/common/tortls.h b/src/common/tortls.h index 211c8255ba..968430d4c9 100644 --- a/src/common/tortls.h +++ b/src/common/tortls.h @@ -33,7 +33,8 @@ typedef struct tor_tls_t tor_tls_t; #define TOR_TLS_WANTWRITE -1 #define TOR_TLS_DONE 0 -/** DOCDOC XXXX021 also rename me. */ +/** Collection of case statements for all TLS errors that are not due to + * underlying IO failure. */ #define CASE_TOR_TLS_ERROR_ANY_NONIO \ case TOR_TLS_ERROR_MISC: \ case TOR_TLS_ERROR_CONNREFUSED: \ diff --git a/src/or/config.c b/src/or/config.c index 0dd9a0f03f..c0fb22bf67 100644 --- a/src/or/config.c +++ b/src/or/config.c @@ -1191,7 +1191,8 @@ options_act_reversible(or_options_t *old_options, char **msg) return r; } -/** DOCDOC */ +/** If we need to have a GEOIP ip-to-country map to run with our configured + * options, return 1 and set *reason_out to a description of why. */ int options_need_geoip_info(or_options_t *options, const char **reason_out) { diff --git a/src/or/connection_edge.c b/src/or/connection_edge.c index 0775e39645..fe415ce236 100644 --- a/src/or/connection_edge.c +++ b/src/or/connection_edge.c @@ -1361,6 +1361,11 @@ consider_plaintext_ports(edge_connection_t *conn, uint16_t port) return 0; } +/** How many times do we try connecting with an exit configured via + * TrackHostExits before concluding that it won't work any more and trying a + * different one? */ +#define TRACKHOSTEXITS_RETRIES 5 + /** Connection conn just finished its socks handshake, or the * controller asked us to take care of it. If circ is defined, * then that's where we'll want to attach it. Otherwise we have to @@ -1500,8 +1505,6 @@ connection_ap_handshake_rewrite_and_attach(edge_connection_t *conn, if (s) { if (s[1] != '\0') { conn->chosen_exit_name = tor_strdup(s+1); -/* DOCDOC */ -#define TRACKHOSTEXITS_RETRIES 5 if (remapped_to_exit) /* 5 tries before it expires the addressmap */ conn->chosen_exit_retries = TRACKHOSTEXITS_RETRIES; *s = 0; diff --git a/src/or/directory.c b/src/or/directory.c index 97613b0f0b..13c3f71ab8 100644 --- a/src/or/directory.c +++ b/src/or/directory.c @@ -2179,13 +2179,13 @@ write_http_response_header(dir_connection_t *conn, ssize_t length, } #ifdef INSTRUMENT_DOWNLOADS -/** 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. */ typedef struct request_t { - uint64_t bytes; - uint64_t count; + uint64_t bytes; /**< How many bytes have we transferred? */ + uint64_t count; /**< How many requests have we made? */ } request_t; +/** 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 request_t. */ static strmap_t *request_map = NULL; static void @@ -2222,7 +2222,7 @@ note_client_request(int purpose, int compressed, size_t bytes) tor_free(key); } -/** DOCDOC */ +/** Helper: initialize the request map to instrument downloads. */ static void ensure_request_map_initialized(void) { @@ -3394,6 +3394,8 @@ dir_routerdesc_download_failed(smartlist_t *failed, int status_code, * every 10 or 60 seconds (FOO_DESCRIPTOR_RETRY_INTERVAL) in main.c. */ } +/** Helper. Compare two fp_pair_t objects, and return -1, 0, or 1 as + * appropriate. */ static int _compare_pairs(const void **a, const void **b) { @@ -3405,7 +3407,10 @@ _compare_pairs(const void **a, const void **b) return memcmp(fp1->second, fp2->second, DIGEST_LEN); } -/** DOCDOC */ +/** Divide a string res of the form FP1-FP2+FP3-FP4...[.z], where each + * FP is a hex-encoded fingerprint, into a sequence of distinct sorted + * fp_pair_t. Skip malformed pairs. On success, return 0 and add those + * fp_pair_t into pairs_out. On failure, return -1. */ int dir_split_resource_into_fingerprint_pairs(const char *res, smartlist_t *pairs_out) diff --git a/src/or/dns.c b/src/or/dns.c index 2b6ea88482..9f22e28f01 100644 --- a/src/or/dns.c +++ b/src/or/dns.c @@ -229,7 +229,8 @@ dns_reset(void) return 0; } -/**DOCDOC*/ +/** Return true iff the most recent attempt to initialize the DNS subsystem + * failed. */ int has_dns_init_failed(void) { diff --git a/src/or/eventdns.c b/src/or/eventdns.c index cd5629bd1a..6a56b508be 100644 --- a/src/or/eventdns.c +++ b/src/or/eventdns.c @@ -307,7 +307,7 @@ static int global_max_retransmits = 3; /* number of times we'll retransmit a req /* number of timeouts in a row before we consider this server to be down */ static int global_max_nameserver_timeout = 3; -/* DOCDOC */ +/* true iff we should use the 0x20 hack. */ static int global_randomize_case = 1; /* These are the timeout values for nameservers. If we find a nameserver is down */ diff --git a/src/or/geoip.c b/src/or/geoip.c index a0f0d4ae90..a4c1e2794d 100644 --- a/src/or/geoip.c +++ b/src/or/geoip.c @@ -23,10 +23,12 @@ typedef struct geoip_entry_t { intptr_t country; /**< An index into geoip_countries */ } geoip_entry_t; -/** DOCDOC */ +/** For how many periods should we remember per-country request history? */ #define REQUEST_HIST_LEN 3 +/** How long are the periods for which we should remember request history? */ #define REQUEST_HIST_PERIOD (8*60*60) +/** A per-country record for GeoIP request history */ typedef struct geoip_country_t { char countrycode[3]; uint32_t n_v2_ns_requests[REQUEST_HIST_LEN]; @@ -269,8 +271,10 @@ static HT_HEAD(clientmap, clientmap_entry_t) client_history = /** Time at which we started tracking client IP history. */ static time_t client_history_starts = 0; -/** DOCDOC */ +/** When did the current period of checking per-country request history + * start? */ static time_t current_request_period_starts = 0; +/** How many older request periods are we remembering? */ static int n_old_request_periods = 0; /** Hashtable helper: compute a hash of a clientmap_entry_t. */ @@ -312,7 +316,7 @@ geoip_note_client_seen(geoip_client_action_t action, #endif } - /* DOCDOC */ + /* Rotate the current request period. */ while (current_request_period_starts + REQUEST_HIST_PERIOD < now) { if (!geoip_countries) geoip_countries = smartlist_create(); @@ -430,7 +434,8 @@ _c_hist_compare(const void **_a, const void **_b) return strcmp(a->country, b->country); } -/*DOCDOC*/ +/** How long do we have to have observed per-country request history before we + * are willing to talk about it? */ #define GEOIP_MIN_OBSERVATION_TIME (12*60*60) static INLINE unsigned @@ -529,7 +534,9 @@ geoip_get_client_history(time_t now, geoip_client_action_t action) return result; } -/**DOCDOC*/ +/** Return a newly allocated string holding the per-country request history + * for action in a format suitable for an extra-info document, or NULL + * on failure. */ char * geoip_get_request_history(time_t now, geoip_client_action_t action) { diff --git a/src/or/relay.c b/src/or/relay.c index 341f71f3de..2ced83acbd 100644 --- a/src/or/relay.c +++ b/src/or/relay.c @@ -1844,7 +1844,13 @@ append_cell_to_circuit_queue(circuit_t *circ, or_connection_t *orconn, } } -/** DOCDOC */ +/** Append an encoded value of addr to payload_out, which must + * have at least 18 bytes of free space. The encoding is, as specified in + * tor-spec.txt: + * RESOLVED_TYPE_IPV4 or RESOLVED_TYPE_IPV6 [1 byte] + * LENGTH [1 byte] + * ADDRESS [length bytes] + * Return the number of bytes added, or -1 on error */ int append_address_to_payload(char *payload_out, const tor_addr_t *addr) { @@ -1867,7 +1873,10 @@ append_address_to_payload(char *payload_out, const tor_addr_t *addr) } } -/** DODOC */ +/** Given payload_len bytes at payload, starting with an address + * encoded as by append_address_to_payload(), try to decode the address into + * *addr_out. Return the next byte in the payload after the address on + * success, or NULL on failure. */ const char * decode_address_from_payload(tor_addr_t *addr_out, const char *payload, int payload_len) diff --git a/src/or/rephist.c b/src/or/rephist.c index 088635cda4..45dbd6c4fc 100644 --- a/src/or/rephist.c +++ b/src/or/rephist.c @@ -777,7 +777,8 @@ rep_hist_record_mtbf_data(void) return -1; } -/** DOCDOC */ +/** Format the current tracked status of the router in hist at time + * now for analysis; return it in a newly allocated string. */ static char * rep_hist_format_router_status(or_history_t *hist, time_t now) { @@ -821,12 +822,17 @@ rep_hist_format_router_status(or_history_t *hist, time_t now) return tor_strdup(buf); } -/* DOCDOC */ +/** The last stability analysis document that we created, or NULL if we never + * have created one. */ static char *last_stability_doc = NULL; +/** The last time we created a stability analysis document, or 0 if we never + * have created one. */ static time_t built_last_stability_doc_at = 0; +/** Shortest allowable time between building two stability documents. */ #define MAX_STABILITY_DOC_BUILD_RATE (3*60) -/* DOCDOC */ +/** Return a pointer to a NUL-terminated document describing our view of the + * stability of the routers we've been tracking. Return NULL on failure. */ const char * rep_hist_get_router_stability_doc(time_t now) { diff --git a/src/or/routerlist.c b/src/or/routerlist.c index df35a202d2..f7bc4e0ecb 100644 --- a/src/or/routerlist.c +++ b/src/or/routerlist.c @@ -4808,12 +4808,18 @@ struct routerset_t { * a router belongs to the set if it is _rejected_ by this policy. */ smartlist_t *policies; - /** DOCDOC */ + /** A human-readable description of what this routerset is for. Used in + * log messages. */ char *description; - /** DOCDOC */ + /** A list of the country codes in this set. */ smartlist_t *country_names; + /** Total number of countries we knew about when we built countries. */ int n_countries; + /** Bit array mapping the return value of geoip_get_country() to 1 iff the + * country is a member of this routerset. Note that we MUST call + * routerset_refresh_countries() whenever the geoip country list is + * reloaded. */ bitarray_t *countries; }; @@ -4830,7 +4836,8 @@ routerset_new(void) return result; } -/** DOCDOC */ +/** If c is a country code in the form {cc}, return a newly allocated + * string holding the "cc" part. Else, return NULL. */ static char * routerset_get_countryname(const char *c) { @@ -4981,14 +4988,15 @@ routerset_is_list(const routerset_t *set) smartlist_len(set->policies) == 0; } -/** DOCDOC */ +/** Return true iff we need a GeoIP IP-to-country database to make sense of + * set. */ int routerset_needs_geoip(const routerset_t *set) { return set && smartlist_len(set->country_names); } -/** DOCDOC */ +/** Return true iff there are no entries in set. */ static int routerset_is_empty(const routerset_t *set) { @@ -4996,8 +5004,12 @@ routerset_is_empty(const routerset_t *set) } /** Helper. Return true iff set contains a router based on the other - * provided fields. Return higher values for more specific subentries. - (If country is -1, then we take the country from addr.) */ + * provided fields. Return higher values for more specific subentries: a + * single router is more specific than an address range of routers, which is + * more specific in turn than a country code. + * + * (If country is -1, then we take the country + * from addr.) */ static int routerset_contains(const routerset_t *set, const tor_addr_t *addr, uint16_t orport, @@ -5102,9 +5114,10 @@ routerset_get_all_routers(smartlist_t *out, const routerset_t *routerset, } } -/** Add to target every node from source that is in - * include not excluded in a more specific fashion by - * exclude. DOCDOC */ +/** Add to target every routerinfo_t from source that is in + * include, but not excluded in a more specific fashion by + * exclude. If running_only, only include running routers. + */ void routersets_get_disjunction(smartlist_t *target, const smartlist_t *source, @@ -5217,14 +5230,15 @@ routerset_free(routerset_t *routerset) tor_free(routerset); } -/** DOCDOC */ +/** Refresh the country code of ri. This function MUST be called on + * each router when the GeoIP database is reloaded, and on all new routers. */ void routerinfo_set_country(routerinfo_t *ri) { ri->country = geoip_get_country_by_ip(ri->addr); } -/** DOCDOC */ +/** Set the country code of all routers in the routerlist. */ void routerlist_refresh_countries(void) {