commit f68c042637d253dfb3160357ba2b9ec530cb48ef Author: Nick Mathewson <nickm@torproject.org> Date: Mon Jun 4 18:50:13 2012 -0400 Resolve all currently pending DOCDOC items in master --- src/common/compat.c | 3 +- src/common/util.c | 12 +++++++- src/common/util.h | 4 ++- src/or/config.c | 59 +++++++++++++++++++++++++++++++-------------- src/or/connection.c | 13 +++++++--- src/or/connection_edge.c | 10 ++++---- src/or/connection_or.c | 3 +- src/or/directory.c | 5 +++- src/or/networkstatus.c | 6 +++- src/or/or.h | 5 ++- src/or/routerlist.c | 13 +++++++--- src/or/routerparse.c | 5 +++- 12 files changed, 95 insertions(+), 43 deletions(-) diff --git a/src/common/compat.c b/src/common/compat.c index 0931061..49a4afe 100644 --- a/src/common/compat.c +++ b/src/common/compat.c @@ -143,7 +143,8 @@ tor_open_cloexec(const char *path, int flags, unsigned mode) return fd; } -/** DOCDOC */ +/** As fpoen(path,mode), but ensures that the O_CLOEXEC bit is set on the + * underlying file handle. */ FILE * tor_fopen_cloexec(const char *path, const char *mode) { diff --git a/src/common/util.c b/src/common/util.c index e7979d8..b3145ae 100644 --- a/src/common/util.c +++ b/src/common/util.c @@ -3323,7 +3323,15 @@ process_handle_new(void) return out; } -/*DOCDOC*/ +/** + * @name child-process states + * + * Each of these values represents a possible state that a child process can + * be in. They're used to determine what to say when telling the parent how + * far along we were before failure. + * + * @{ + */ #define CHILD_STATE_INIT 0 #define CHILD_STATE_PIPE 1 #define CHILD_STATE_MAXFD 2 @@ -3334,7 +3342,7 @@ process_handle_new(void) #define CHILD_STATE_CLOSEFD 7 #define CHILD_STATE_EXEC 8 #define CHILD_STATE_FAILEXEC 9 - +/** @} */ /** Start a program in the background. If <b>filename</b> contains a '/', then * it will be treated as an absolute or relative path. Otherwise, on * non-Windows systems, the system path will be searched for <b>filename</b>. diff --git a/src/common/util.h b/src/common/util.h index 36601fa..ae40898 100644 --- a/src/common/util.h +++ b/src/common/util.h @@ -409,8 +409,10 @@ void set_environment_variable_in_smartlist(struct smartlist_t *env_vars, #define PROCESS_STATUS_ERROR -1 #ifdef UTIL_PRIVATE -/*DOCDOC*/ +/** Structure to represent the state of a process with which Tor is + * communicating. The contents of this structure are private to util.c */ struct process_handle_t { + /** One of the PROCESS_STATUS_* values */ int status; #ifdef _WIN32 HANDLE stdout_pipe; diff --git a/src/or/config.c b/src/or/config.c index 8a19ed6..5f5960f 100644 --- a/src/or/config.c +++ b/src/or/config.c @@ -675,11 +675,12 @@ static const config_format_t state_format = { /** Command-line and config-file options. */ static or_options_t *global_options = NULL; -/** DOCDOC */ +/** The fallback options_t object; this is where we look for options not + * in torrc before we fall back to Tor's defaults. */ static or_options_t *global_default_options = NULL; /** Name of most recently read torrc file. */ static char *torrc_fname = NULL; -/** DOCDOC */ +/** Name of the most recently read torrc-defaults file.*/ static char *torrc_defaults_fname; /** Persistent serialized state. */ static or_state_t *global_state = NULL; @@ -4345,8 +4346,8 @@ get_windows_conf_root(void) } #endif -/** Return the default location for our torrc file. - * DOCDOC defaults_file */ +/** Return the default location for our torrc file (if <b>defaults_file</b> is + * false), or for the torrc-defaults file (if <b>defaults_file</b> is true). */ static const char * get_default_conf_file(int defaults_file) { @@ -4396,12 +4397,21 @@ check_nickname_list(const char *lst, const char *name, char **msg) return r; } -/** Learn config file name from command line arguments, or use the default, - * DOCDOC defaults_file */ +/** Learn config file name from command line arguments, or use the default. + * + * If <b>defaults_file</b> is true, we're looking for torrc-defaults; + * otherwise, we're looking for the regular torrc_file. + * + * Set *<b>using_default_fname</b> to true if we're using the default + * configuration file name; or false if we've set it from the command line. + * + * Set *<b>ignore_missing_torrc</b> to true if we should ignore the resulting + * filename if it doesn't exist. + */ static char * find_torrc_filename(int argc, char **argv, int defaults_file, - int *using_default_torrc, int *ignore_missing_torrc) + int *using_default_fname, int *ignore_missing_torrc) { char *fname=NULL; int i; @@ -4427,14 +4437,14 @@ find_torrc_filename(int argc, char **argv, fname = absfname; } - *using_default_torrc = 0; + *using_default_fname = 0; ++i; } else if (ignore_opt && !strcmp(argv[i],ignore_opt)) { *ignore_missing_torrc = 1; } } - if (*using_default_torrc) { + if (*using_default_fname) { /* didn't find one, try CONFDIR */ const char *dflt = get_default_conf_file(defaults_file); if (dflt && file_status(dflt) == FN_FILE) { @@ -4458,8 +4468,13 @@ find_torrc_filename(int argc, char **argv, return fname; } -/** Load torrc from disk, setting torrc_fname if successful. - * DOCDOC defaults_file */ +/** Load a configuration file from disk, setting torrc_fname or + * torrc_defaults_fname if successful. + * + * If <b>defaults_file</b> is true, load torrc-defaults; otherwise load torrc. + * + * Return the contents of the file on success, and NULL on failure. + */ static char * load_torrc_from_disk(int argc, char **argv, int defaults_file) { @@ -5455,7 +5470,10 @@ warn_nonlocal_client_ports(const smartlist_t *ports, const char *portname) } SMARTLIST_FOREACH_END(port); } -/** DOCDOC */ +/** Given a list of port_cfg_t in <b>ports</b>, warn any controller port there + * is listening on any non-loopback address. If <b>forbid</b> is true, + * then emit a stronger warning and remove the port from the list. + */ static void warn_nonlocal_controller_ports(smartlist_t *ports, unsigned forbid) { @@ -5839,10 +5857,12 @@ parse_port_config(smartlist_t *out, return retval; } -/** DOCDOC */ +/** Parse a list of config_line_t for an AF_UNIX unix socket listener option + * from <b>cfg</b> and add them to <b>out</b>. No fancy options are + * supported: the line contains nothing but the path to the AF_UNIX socket. */ static int -parse_socket_config(smartlist_t *out, const config_line_t *cfg, - int listener_type) +parse_unix_socket_config(smartlist_t *out, const config_line_t *cfg, + int listener_type) { if (!out) @@ -5928,9 +5948,9 @@ parse_ports(const or_options_t *options, int validate_only, "configuration"); goto err; } - if (parse_socket_config(ports, - options->ControlSocket, - CONN_TYPE_CONTROL_LISTENER) < 0) { + if (parse_unix_socket_config(ports, + options->ControlSocket, + CONN_TYPE_CONTROL_LISTENER) < 0) { *msg = tor_strdup("Invalid ControlSocket configuration"); goto err; } @@ -5980,7 +6000,8 @@ parse_ports(const or_options_t *options, int validate_only, return retval; } -/** DOCDOC */ +/** Given a list of <b>port_cfg_t</b> in <b>ports</b>, check them for internal + * consistency and warn as appropriate. */ static int check_server_ports(const smartlist_t *ports, const or_options_t *options) diff --git a/src/or/connection.c b/src/or/connection.c index beeeb2a..3ff6a71 100644 --- a/src/or/connection.c +++ b/src/or/connection.c @@ -1659,7 +1659,8 @@ connection_send_socks5_connect(connection_t *conn) conn->proxy_state = PROXY_SOCKS5_WANT_CONNECT_OK; } -/** DOCDOC */ +/** Wrapper around fetch_from_(buf/evbuffer)_socks_client: see those functions + * for documentation of its behavior. */ static int connection_fetch_from_buf_socks_client(connection_t *conn, int state, char **reason) @@ -2239,7 +2240,9 @@ global_write_bucket_low(connection_t *conn, size_t attempt, int priority) return 0; } -/** DOCDOC */ +/** Helper: adjusts our bandwidth history and informs the controller as + * appropriate, given that we have just read <b>num_read</b> bytes and written + * <b>num_written</b> bytes on <b>conn</b>. */ static void record_num_bytes_transferred_impl(connection_t *conn, time_t now, size_t num_read, size_t num_written) @@ -2270,7 +2273,8 @@ record_num_bytes_transferred_impl(connection_t *conn, } #ifdef USE_BUFFEREVENTS -/** DOCDOC */ +/** Wrapper around fetch_from_(buf/evbuffer)_socks_client: see those functions + * for documentation of its behavior. */ static void record_num_bytes_transferred(connection_t *conn, time_t now, size_t num_read, size_t num_written) @@ -2592,7 +2596,8 @@ connection_get_rate_limit_totals(uint64_t *read_out, uint64_t *written_out) } } -/** DOCDOC */ +/** Perform whatever operations are needed on <b>conn</b> to enable + * rate-limiting. */ void connection_enable_rate_limiting(connection_t *conn) { diff --git a/src/or/connection_edge.c b/src/or/connection_edge.c index ca4bf3f..4c29e06 100644 --- a/src/or/connection_edge.c +++ b/src/or/connection_edge.c @@ -2673,12 +2673,12 @@ connection_ap_handshake_send_resolve(entry_connection_t *ap_conn) return 0; } -/** Make an AP connection_t, make a new linked connection pair, and attach - * one side to the conn, connection_add it, initialize it to circuit_wait, - * and call connection_ap_handshake_attach_circuit(conn) on it. +/** Make an AP connection_t linked to the connection_t <b>partner</b>. make a + * new linked connection pair, and attach one side to the conn, connection_add + * it, initialize it to circuit_wait, and call + * connection_ap_handshake_attach_circuit(conn) on it. * - * Return the other end of the linked connection pair, or -1 if error. - * DOCDOC partner. + * Return the newly created end of the linked connection pair, or -1 if error. */ entry_connection_t * connection_ap_make_link(connection_t *partner, diff --git a/src/or/connection_or.c b/src/or/connection_or.c index 8aec5d2..6a2f243 100644 --- a/src/or/connection_or.c +++ b/src/or/connection_or.c @@ -2099,7 +2099,8 @@ connection_or_send_auth_challenge_cell(or_connection_t *conn) * * If <b>server</b> is false and <b>signing_key</b> is provided, calculate the * entire authenticator, signed with <b>signing_key</b>. - * DOCDOC return value + * + * Return the length of the cell body on success, and -1 on failure. */ int connection_or_compute_authenticate_cell_body(or_connection_t *conn, diff --git a/src/or/directory.c b/src/or/directory.c index 3d2b955..7531260 100644 --- a/src/or/directory.c +++ b/src/or/directory.c @@ -3788,7 +3788,10 @@ dir_routerdesc_download_failed(smartlist_t *failed, int status_code, * every 10 or 60 seconds (FOO_DESCRIPTOR_RETRY_INTERVAL) in main.c. */ } -/* DOCDOC NM */ +/** Called when a connection to download microdescriptors has failed in whole + * or in part. <b>failed</b> is a list of every microdesc digest we didn't + * get. <b>status_code</b> is the http status code we received. Reschedule the + * microdesc downloads as appropriate. */ static void dir_microdesc_download_failed(smartlist_t *failed, int status_code) diff --git a/src/or/networkstatus.c b/src/or/networkstatus.c index 3646ee6..0f51676 100644 --- a/src/or/networkstatus.c +++ b/src/or/networkstatus.c @@ -1183,7 +1183,8 @@ update_v2_networkstatus_cache_downloads(time_t now) } } -/** DOCDOC */ +/** Return true iff, given the options listed in <b>options</b>, <b>flavor</b> + * is the flavor of a consensus networkstatus that we would like to fetch. */ static int we_want_to_fetch_flavor(const or_options_t *options, int flavor) { @@ -1455,7 +1456,8 @@ networkstatus_get_latest_consensus(void) return current_consensus; } -/** DOCDOC */ +/** Return the latest consensus we have whose flavor matches <b>f</b>, or NULL + * if we don't have one. */ networkstatus_t * networkstatus_get_latest_consensus_by_flavor(consensus_flavor_t f) { diff --git a/src/or/or.h b/src/or/or.h index 76681c9..5d620db 100644 --- a/src/or/or.h +++ b/src/or/or.h @@ -1251,7 +1251,8 @@ typedef struct or_connection_t { * bandwidthburst. (OPEN ORs only) */ int write_bucket; /**< When this hits 0, stop writing. Like read_bucket. */ #else - /** DOCDOC */ + /** A rate-limiting configuration object to determine how this connection + * set its read- and write- limits. */ /* XXXX we could share this among all connections. */ struct ev_token_bucket_cfg *bucket_cfg; #endif @@ -1729,7 +1730,7 @@ typedef struct { uint16_t or_port; /**< Port for TLS connections. */ uint16_t dir_port; /**< Port for HTTP directory connections. */ - /* DOCDOC */ + /** A router's IPv6 address, if it has one. */ /* XXXXX187 Actually these should probably be part of a list of addresses, * not just a special case. Use abstractions to access these; don't do it * directly. */ diff --git a/src/or/routerlist.c b/src/or/routerlist.c index 36a282a..db0844d 100644 --- a/src/or/routerlist.c +++ b/src/or/routerlist.c @@ -4188,9 +4188,9 @@ any_trusted_dir_is_v1_authority(void) /** For every current directory connection whose purpose is <b>purpose</b>, * and where the resource being downloaded begins with <b>prefix</b>, split - * rest of the resource into base16 fingerprints, decode them, and set the + * rest of the resource into base16 fingerprints (or base64 fingerprints if + * purpose==DIR_PURPPOSE_FETCH_MICRODESC), decode them, and set the * corresponding elements of <b>result</b> to a nonzero value. - * DOCDOC purpose==microdesc */ static void list_pending_downloads(digestmap_t *result, @@ -4235,8 +4235,13 @@ list_pending_descriptor_downloads(digestmap_t *result, int extrainfo) list_pending_downloads(result, purpose, "d/"); } -/** DOCDOC */ -/*XXXX NM should use digest256, if one comes into being. */ +/** For every microdescriptor we are currently downloading by descriptor + * digest, set result[d] to (void*)1. (Note that microdescriptor digests + * are 256-bit, and digestmap_t only holds 160-bit digests, so we're only + * getting the first 20 bytes of each digest here.) + * + * XXXX Let there be a digestmap256_t, and use that instead. + */ void list_pending_microdesc_downloads(digestmap_t *result) { diff --git a/src/or/routerparse.c b/src/or/routerparse.c index 781c578..d86c0cf 100644 --- a/src/or/routerparse.c +++ b/src/or/routerparse.c @@ -4169,7 +4169,10 @@ _find_by_keyword(smartlist_t *s, directory_keyword keyword, return tok; } -/** DOCDOC */ +/** If there are any directory_token_t entries in <b>s</b> whose keyword is + * <b>k</b>, return a newly allocated smartlist_t containing all such entries, + * in the same order in which they occur in <b>s</b>. Otherwise return + * NULL. */ static smartlist_t * find_all_by_keyword(smartlist_t *s, directory_keyword k) {