From d2893398f6c98f4ad82f05c41fb9ca40c5020015 Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Fri, 16 Feb 2007 20:39:37 +0000 Subject: [PATCH] r11832@catbus: nickm | 2007-02-16 15:31:59 -0500 Fix 35 remaining DOCDOC comments. Yowza. svn:r9596 --- src/common/tortls.c | 7 ++++--- src/common/util.c | 11 ++++++----- src/or/circuitbuild.c | 3 ++- src/or/circuitlist.c | 8 +++++--- src/or/circuituse.c | 8 +++++--- src/or/dirserv.c | 25 ++++++++++++++----------- src/or/main.c | 11 ++++++----- src/or/policies.c | 6 ++++-- src/or/router.c | 16 ++++++++++------ 9 files changed, 56 insertions(+), 39 deletions(-) diff --git a/src/common/tortls.c b/src/common/tortls.c index 365af60681..e8984603d1 100644 --- a/src/common/tortls.c +++ b/src/common/tortls.c @@ -103,7 +103,8 @@ tls_log_errors(int severity, const char *doing) } } -/** DOCDOC */ +/** Convert an errno (or a WSAerrno on windows) into a TOR_TLS_* error + * code. */ static int tor_errno_to_tls_error(int e) { @@ -206,7 +207,7 @@ tor_tls_init(void) } } -/** DOCDOC */ +/** Free all global TLS structures. */ void tor_tls_free_all(void) { @@ -672,7 +673,7 @@ tor_tls_peer_has_cert(tor_tls_t *tls) return 1; } -/** DOCDOC */ +/** Warn that a certificate lifetime extends through a certain range. */ static void log_cert_lifetime(X509 *cert, const char *problem) { diff --git a/src/common/util.c b/src/common/util.c index 11174e46d3..a2e10b77a1 100644 --- a/src/common/util.c +++ b/src/common/util.c @@ -862,9 +862,9 @@ tv_addms(struct timeval *a, long ms) a->tv_usec %= 1000000; } -/** DOCDOC */ +/** Yield true iff y is a leap-year */ #define IS_LEAPYEAR(y) (!(y % 4) && ((y % 100) || !(y % 400))) -/** DOCDOC */ +/** Helper: Return the number of leap-days between Jan 1, y1 and Jan 1, y2. */ static int n_leapdays(int y1, int y2) { @@ -1957,11 +1957,12 @@ get_interface_address(int severity, uint32_t *addr) #ifndef MS_WINDOWS /* Based on code contributed by christian grothoff */ -/** DOCDOC */ +/** True iff we've called start_daemon. */ static int start_daemon_called = 0; -/** DOCDOC */ +/** True iff we've called finish_daemon. */ static int finish_daemon_called = 0; -/** DOCDOC */ +/** Socketpair used to communicate between parent and child process while + * daemonizing. */ static int daemon_filedes[2]; /** Start putting the process into daemon mode: fork and drop all resources * except standard fds. The parent process never returns, but stays around diff --git a/src/or/circuitbuild.c b/src/or/circuitbuild.c index ac76c6fea0..1420525e1b 100644 --- a/src/or/circuitbuild.c +++ b/src/or/circuitbuild.c @@ -1110,7 +1110,8 @@ router_handles_some_port(routerinfo_t *router, smartlist_t *needed_ports) return 0; } -/* DOCDOC */ +/** Return true iff conn is waiting for a general circuit to be + * built. */ static int ap_stream_wants_exit_attention(connection_t *conn) { diff --git a/src/or/circuitlist.c b/src/or/circuitlist.c index 3c494be12f..3f00f2da7d 100644 --- a/src/or/circuitlist.c +++ b/src/or/circuitlist.c @@ -48,14 +48,15 @@ _orconn_circid_entries_eq(orconn_circid_circuit_map_t *a, return a->or_conn == b->or_conn && a->circ_id == b->circ_id; } -/** DOCDOC */ +/** Helper: return a hash based on circuit ID and the pointer value of + * or_conn in a. */ static INLINE unsigned int _orconn_circid_entry_hash(orconn_circid_circuit_map_t *a) { return (((unsigned)a->circ_id)<<16) ^ (unsigned)(uintptr_t)(a->or_conn); } -/** DOCDOC */ +/** Map from [orconn,circid] to circuit. */ static HT_HEAD(orconn_circid_map, orconn_circid_circuit_map_t) orconn_circid_circuit_map = HT_INITIALIZER(); HT_PROTOTYPE(orconn_circid_map, orconn_circid_circuit_map_t, node, @@ -319,7 +320,8 @@ origin_circuit_new(void) return circ; } -/** DOCDOC */ +/** Allocate a new or_circuit_t, connected to p_conn as + * p_circ_id. If p_conn is NULL, the circuit is unattached. */ or_circuit_t * or_circuit_new(uint16_t p_circ_id, or_connection_t *p_conn) { diff --git a/src/or/circuituse.c b/src/or/circuituse.c index fd2b0cfa29..6cc7f54f07 100644 --- a/src/or/circuituse.c +++ b/src/or/circuituse.c @@ -566,10 +566,11 @@ circuit_expire_old_circuits(time_t now) } } -/** DOCDOC */ +/** Number of circuits to open at once when testing our bandwidth. */ #define NUM_PARALLEL_TESTING_CIRCS 4 -/** DOCDOC */ +/** True iff we've ever opened enough testing circuits to test our + * bandwidth. */ static int have_performed_bandwidth_test = 0; /** Reset have_performed_bandwidth_test, so we'll start building @@ -776,7 +777,8 @@ circuit_build_failed(origin_circuit_t *circ) * circuit_launch_new and circuit_*_failure_count. */ static int n_circuit_failures = 0; -/** DOCDOC */ +/** Before the last time we called circuit_reset_failure_count(), were + * there a lot of failures? */ static int did_circs_fail_last_period = 0; /** Don't retry launching a new circuit if we try this many times with no diff --git a/src/or/dirserv.c b/src/or/dirserv.c index e7ac7bccc2..2107f9e4ac 100644 --- a/src/or/dirserv.c +++ b/src/or/dirserv.c @@ -52,23 +52,24 @@ static void clear_cached_dir(cached_dir_t *d); #define FP_REJECT 4 /**< We will not publish this router. */ #define FP_BADEXIT 8 /**< We'll tell clients not to use this as an exit. */ -/** DOCDOC */ +/** Encapsulate a nickname and an FP_* status; target of status_by_digest + * map. */ typedef struct router_status_t { char nickname[MAX_NICKNAME_LEN+1]; uint32_t status; } router_status_t; /** List of nickname-\>identity fingerprint mappings for all the routers - * that we name. Used to prevent router impersonation. DODDOC */ + * that we name. Used to prevent router impersonation. */ typedef struct authdir_config_t { strmap_t *fp_by_name; /* Map from lc nickname to fingerprint */ - digestmap_t *status_by_digest; /* Map from digest to FP_x mask */ + digestmap_t *status_by_digest; /* Map from digest to router_status_t. */ } authdir_config_t; /** Should be static; exposed for testing */ authdir_config_t *fingerprint_list = NULL; -/** DOCDOC */ +/** Allocate and return a new, empty, authdir_config_t. */ static authdir_config_t * authdir_config_new(void) { @@ -576,11 +577,12 @@ dirserv_add_descriptor(const char *desc, const char **msg) } } -/** DOCDOC */ +/** Helper: return true iff the boolean values of a and b are + * different. */ static INLINE int bool_neq(int a, int b) { - return (a && !b) || (!a && b); + return (a) ? !b : b; } /** Remove all descriptors whose nicknames or fingerprints no longer @@ -1338,7 +1340,8 @@ dirserv_get_runningrouters(const char **rr, int compress) /** For authoritative directories: the current (v2) network status */ static cached_dir_t *the_v2_networkstatus = NULL; -/** DOCDOC */ +/** Return true iff our opinion of the routers has been stale for long + * enough that we should generate a new network status doc. */ static int should_generate_v2_networkstatus(void) { @@ -1488,11 +1491,11 @@ dirserv_compute_performance_thresholds(routerlist_t *rl) static cached_dir_t * generate_v2_networkstatus(void) { -/** DOCDOC */ +/** Longest status flag name that we generate. */ #define LONGEST_STATUS_FLAG_NAME_LEN 9 -/** DOCDOC */ -#define N_STATUS_FLAGS 9 -/** DOCDOC */ +/** Maximum number of status flags we'll apply to one router. */ +#define N_STATUS_FLAGS 10 +/** Amount of space to allocate for each entry. (r line and s line.) */ #define RS_ENTRY_LEN \ ( /* first line */ \ MAX_NICKNAME_LEN+BASE64_DIGEST_LEN*2+ISO_TIME_LEN+INET_NTOA_BUF_LEN+ \ diff --git a/src/or/main.c b/src/or/main.c index cff1a434b3..b2d398b0ca 100644 --- a/src/or/main.c +++ b/src/or/main.c @@ -58,7 +58,8 @@ static time_t time_to_check_for_correct_dns = 0; /** Array of all open connections. The first n_conns elements are valid. */ static connection_t *connection_array[MAXCONNECTIONS+1] = { NULL }; -/** DOCDOC */ +/** List of connections that have been marked for close and need to be freed + * and removed from connection_array. */ static smartlist_t *closeable_connection_lst = NULL; static int n_conns=0; /**< Number of connections currently active. */ @@ -818,7 +819,7 @@ run_scheduled_events(time_t now) if (any_trusted_dir_is_v1_authority()) directory_get_from_dirserver(DIR_PURPOSE_FETCH_DIR, NULL, 1); } -/** DOCDOC */ +/** How often do we (as a cache) fetch a new V1 directory? */ #define V1_DIR_FETCH_PERIOD (6*60*60) time_to_fetch_directory = now + V1_DIR_FETCH_PERIOD; } @@ -828,7 +829,7 @@ run_scheduled_events(time_t now) if (!authdir_mode(options) || !options->V1AuthoritativeDir) { directory_get_from_dirserver(DIR_PURPOSE_FETCH_RUNNING_LIST, NULL, 1); } -/** DOCDOC */ +/** How often do we (as a cache) fetch a new V1 runningrouters document? */ #define V1_RUNNINGROUTERS_FETCH_PERIOD (30*60) time_to_fetch_running_routers = now + V1_RUNNINGROUTERS_FETCH_PERIOD; @@ -955,9 +956,9 @@ run_scheduled_events(time_t now) } } -/** DOCDOC */ +/** Libevent timer: used to invoke second_elapsed_callback once per second. */ static struct event *timeout_event = NULL; -/** DOCDOC */ +/** Number of libevent errors in the last second: we die if we get too many. */ static int n_libevent_errors = 0; /** Libevent callback: invoked once every second. */ diff --git a/src/or/policies.c b/src/or/policies.c index 392385ce5a..3129ea35f7 100644 --- a/src/or/policies.c +++ b/src/or/policies.c @@ -156,7 +156,8 @@ addr_policy_permits_address(uint32_t addr, uint16_t port, } } -/** DOCDOC */ +/** Return true iff we think our firewall will let us make an OR connection to + * addr:port. */ int fascist_firewall_allows_address_or(uint32_t addr, uint16_t port) { @@ -164,7 +165,8 @@ fascist_firewall_allows_address_or(uint32_t addr, uint16_t port) reachable_or_addr_policy); } -/** DOCDOC */ +/** Return true iff we think our firewall will let us make a directory + * connection to addr:port. */ int fascist_firewall_allows_address_dir(uint32_t addr, uint16_t port) { diff --git a/src/or/router.c b/src/or/router.c index 220a3a5195..d4502c2274 100644 --- a/src/or/router.c +++ b/src/or/router.c @@ -28,13 +28,15 @@ extern long stats_n_seconds_working; */ static tor_mutex_t *key_lock=NULL; static time_t onionkey_set_at=0; /**< When was onionkey last changed? */ -/** DOCDOC */ +/** Current private onionskin decryption key: used to decode CREATE cells. */ static crypto_pk_env_t *onionkey=NULL; -/** DOCDOC */ +/** Previous private onionskin decription key: used to decode CREATE cells + * generated by client that have an older version of our descriptor. */ static crypto_pk_env_t *lastonionkey=NULL; -/** DOCDOC */ +/** Private "identity key": used to sign directory info and TLS + * certificates. Never changes. */ static crypto_pk_env_t *identitykey=NULL; -/** DOCDOC */ +/** Digest of identitykey. */ static char identitykey_digest[DIGEST_LEN]; /** Replace the current onion key with k. Does not affect lastonionkey; @@ -999,7 +1001,8 @@ check_descriptor_bandwidth_changed(time_t now) } } -/** DOCDOC */ +/** Note at log level severity that our best guess of address has changed from + * prev to cur */ static void log_addr_has_changed(int severity, uint32_t prev, uint32_t cur) { @@ -1050,7 +1053,8 @@ check_descriptor_ipaddress_changed(time_t now) } } -/** DOCDOC */ +/** The most recently guessed value of our IP address, from directory + * headers. */ static uint32_t last_guessed_ip = 0; /** A directory authority told us our IP address is suggestion.