From 558e9899e4d11d8ef194e5bc1761d5d2f6dff450 Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Tue, 23 Dec 2008 17:56:31 +0000 Subject: [PATCH] Document most undocumented variables. svn:r17754 --- src/common/util.c | 3 ++- src/or/command.c | 14 +++++------ src/or/config.c | 32 +++++++++++++----------- src/or/control.c | 16 +++++++++--- src/or/directory.c | 8 +++--- src/or/dirserv.c | 17 ++++++++----- src/or/hibernate.c | 9 +++---- src/or/main.c | 8 +++--- src/or/networkstatus.c | 9 ++++--- src/or/or.h | 8 +++++- src/or/relay.c | 14 +++++++---- src/or/router.c | 9 ++++--- src/or/routerparse.c | 10 +++++--- src/or/test.c | 55 +++++++++++++++++++++--------------------- src/or/test_data.c | 6 +++++ src/or/tor_main.c | 5 +++- 16 files changed, 135 insertions(+), 88 deletions(-) diff --git a/src/common/util.c b/src/common/util.c index 84a40a82a6..4a8d762e4f 100644 --- a/src/common/util.c +++ b/src/common/util.c @@ -1392,7 +1392,8 @@ ftime_definitely_after(time_t now, time_t when) * after when. */ return (now + ftime_skew - ftime_slop) >= when; } -/** Return true if we think that now is definitely before when. */ +/** Return true if we think that now is definitely before when. + */ int ftime_definitely_before(time_t now, time_t when) { diff --git a/src/or/command.c b/src/or/command.c index baa435695f..7ad20f0098 100644 --- a/src/or/command.c +++ b/src/or/command.c @@ -20,19 +20,19 @@ const char command_c_id[] = #include "or.h" -/** Keep statistics about how many of each type of cell we've received. */ +/** How many CELL_PADDING cells have we received, ever? */ uint64_t stats_n_padding_cells_processed = 0; -/* DOCDOC stats_n_create_cells_processed */ +/** How many CELL_CREATE cells have we received, ever? */ uint64_t stats_n_create_cells_processed = 0; -/* DOCDOC stats_n_created_cells_processed */ +/** How many CELL_CREATED cells have we received, ever? */ uint64_t stats_n_created_cells_processed = 0; -/* DOCDOC stats_n_relay_cells_processed */ +/** How many CELL_RELAY cells have we received, ever? */ uint64_t stats_n_relay_cells_processed = 0; -/* DOCDOC stats_n_destroy_cells_processed */ +/** How many CELL_DESTROY cells have we received, ever? */ uint64_t stats_n_destroy_cells_processed = 0; -/* DOCDOC stats_n_versions_cells_processed */ +/** How many CELL_VERSIONS cells have we received, ever? */ uint64_t stats_n_versions_cells_processed = 0; -/* DOCDOC stats_n_netinfo_cells_processed */ +/** How many CELL_NETINFO cells have we received, ever? */ uint64_t stats_n_netinfo_cells_processed = 0; /* These are the main functions for processing cells */ diff --git a/src/or/config.c b/src/or/config.c index fec77e7808..adb4b1950b 100644 --- a/src/or/config.c +++ b/src/or/config.c @@ -54,8 +54,8 @@ typedef struct config_abbrev_t { * you can abbreviate toks as tok". */ #define PLURAL(tok) { #tok, #tok "s", 0, 0 } -/* A list of command-line abbreviations. */ -/* DOCDOC _option_abbrevs */ +/** A list of abbreviations and aliases to map command-line options, obsolete + * option names, or alternative option names, to their current values. */ static config_abbrev_t _option_abbrevs[] = { PLURAL(ExitNode), PLURAL(EntryNode), @@ -92,8 +92,8 @@ static config_abbrev_t _option_abbrevs[] = { { "HashedControlPassword", "__HashedControlSessionPassword", 1, 0}, { NULL, NULL, 0, 0}, }; -/* A list of state-file abbreviations, for compatibility. */ -/* DOCDOC _state_abbrevs */ + +/** A list of state-file "abbreviations," for compatibility. */ static config_abbrev_t _state_abbrevs[] = { { "AccountingBytesReadInterval", "AccountingBytesReadInInterval", 0, 0 }, { "HelperNode", "EntryGuard", 0, 0 }, @@ -346,8 +346,8 @@ static config_var_t _option_vars[] = { { NULL, CONFIG_TYPE_OBSOLETE, 0, NULL } }; -/* Keep defaults synchronous with man page and config value check. */ -/* DOCDOC testing_tor_network_defaults */ +/** Override default values with these if the user sets the TestingTorNetwork + * option. */ static config_var_t testing_tor_network_defaults[] = { V(ServerDNSAllowBrokenConfig, BOOL, "1"), V(DirAllowPrivateAddresses, BOOL, "1"), @@ -372,7 +372,8 @@ static config_var_t testing_tor_network_defaults[] = { #define VAR(name,conftype,member,initvalue) \ { name, CONFIG_TYPE_ ## conftype, STRUCT_OFFSET(or_state_t, member), \ initvalue } -/* DOCDOC _state_vars */ + +/** Array of "state" variables saved to the ~/.tor/state file. */ static config_var_t _state_vars[] = { V(AccountingBytesReadInInterval, MEMUNIT, NULL), V(AccountingBytesWrittenInInterval, MEMUNIT, NULL), @@ -412,7 +413,9 @@ typedef struct config_var_description_t { const char *description; } config_var_description_t; -/* DOCDOC options_description */ +/** Descriptions of the configuration options, to be displayed by online + * option browsers */ +/* XXXX022 did anybody want this? at all? If not, kill it.*/ static config_var_description_t options_description[] = { /* ==== general options */ { "AvoidDiskWrites", "If non-zero, try to write to disk less frequently than" @@ -584,7 +587,7 @@ static config_var_description_t options_description[] = { { NULL, NULL }, }; -/* DOCDOC state_description */ +/** Online description of state variables. */ static config_var_description_t state_description[] = { { "AccountingBytesReadInInterval", "How many bytes have we read in this accounting period?" }, @@ -814,13 +817,12 @@ set_options(or_options_t *new_val, char **msg) return 0; } -/* DOCDOC tor_svn_revision */ extern const char tor_svn_revision[]; /* from tor_main.c */ -/* DOCDOC _version */ +/** The version of this Tor process, as parsed. */ static char *_version = NULL; -/** Return the current Tor version, possibly */ +/** Return the current Tor version. */ const char * get_version(void) { @@ -4617,7 +4619,8 @@ struct unit_table_t { uint64_t multiplier; }; -/* DOCDOC memory_units */ +/** Table to map the names of memory units to the number of bytes they + * contain. */ static struct unit_table_t memory_units[] = { { "", 1 }, { "b", 1<< 0 }, @@ -4645,7 +4648,8 @@ static struct unit_table_t memory_units[] = { { NULL, 0 }, }; -/* DOCDOC time_units */ +/** Table to map the names of time units to the number of seconds they + * contain. */ static struct unit_table_t time_units[] = { { "", 1 }, { "second", 1 }, diff --git a/src/or/control.c b/src/or/control.c index e0ebd7d591..73aad0c384 100644 --- a/src/or/control.c +++ b/src/or/control.c @@ -54,9 +54,13 @@ const char control_c_id[] = * list to find out. **/ typedef uint32_t event_mask_t; -/* DOCDOC global_event_mask1long */ + +/** An event mask of all the events that controller with the LONG_NAMES option + * set is interested in receiving. */ static event_mask_t global_event_mask1long = 0; -/* DOCDOC global_event_mask1short */ + +/** An event mask of all the events that controller with the SHORT_NAMES option + * set is interested in receiving. */ static event_mask_t global_event_mask1short = 0; /** True iff we have disabled log messages from being sent to the controller */ @@ -66,7 +70,11 @@ static int disable_log_messages = 0; * e. */ #define EVENT_IS_INTERESTING(e) \ ((global_event_mask1long|global_event_mask1short) & (1<<(e))) +/** Macro: true if any control connection with the LONG_NAMES option is + * interested in events of type e. */ #define EVENT_IS_INTERESTING1L(e) (global_event_mask1long & (1<<(e))) +/** Macro: true if any control connection with the SHORT_NAMES option is + * interested in events of type e. */ #define EVENT_IS_INTERESTING1S(e) (global_event_mask1short & (1<<(e))) /** If we're using cookie-type authentication, how long should our cookies be? @@ -76,7 +84,9 @@ static int disable_log_messages = 0; /** If true, we've set authentication_cookie to a secret code and * stored it to disk. */ static int authentication_cookie_is_set = 0; -/* DOCDOC authentication_cookie */ +/** If authentication_cookie_is_set, a secret cookie that we've stored to disk + * and which we're using to authenticate controllers. (If the controller can + * read it off disk, it has permission to connect. */ static char authentication_cookie[AUTHENTICATION_COOKIE_LEN]; /** A sufficiently large size to record the last bootstrap phase string. */ diff --git a/src/or/directory.c b/src/or/directory.c index 250fd7ee54..b383ad5e89 100644 --- a/src/or/directory.c +++ b/src/or/directory.c @@ -3268,19 +3268,19 @@ dir_networkstatus_download_failed(smartlist_t *failed, int status_code) }); } -/* DOCDOC server_dl_schedule */ +/** Schedule for when servers should download things in general. */ static const int server_dl_schedule[] = { 0, 0, 0, 60, 60, 60*2, 60*5, 60*15, INT_MAX }; -/* DOCDOC client_dl_schedule */ +/** Schedule for when clients should download things in general. */ static const int client_dl_schedule[] = { 0, 0, 60, 60*5, 60*10, INT_MAX }; -/* DOCDOC server_consensus_dl_schedule */ +/** Schedule for when servers should download consensuses. */ static const int server_consensus_dl_schedule[] = { 0, 0, 60, 60*5, 60*10, 60*30, 60*30, 60*30, 60*30, 60*30, 60*60, 60*60*2 }; -/* DOCDOC client_consensus_dl_schedule */ +/** Schedule for when clients should download consensuses. */ static const int client_consensus_dl_schedule[] = { 0, 0, 60, 60*5, 60*10, 60*30, 60*60, 60*60, 60*60, 60*60*3, 60*60*6, 60*60*12 }; diff --git a/src/or/dirserv.c b/src/or/dirserv.c index 361f44f2e5..71b837f857 100644 --- a/src/or/dirserv.c +++ b/src/or/dirserv.c @@ -30,11 +30,13 @@ const char dirserv_c_id[] = extern time_t time_of_process_start; /* from main.c */ -/** Do we need to regenerate the directory when someone asks for it? */ +/** Do we need to regenerate the v1 directory when someone asks for it? */ static time_t the_directory_is_dirty = 1; -/* DOCDOC runningrouters_is_dirty */ +/** Do we need to regenerate the v1 runningrouters document when somebody + * asks for it? */ static time_t runningrouters_is_dirty = 1; -/* DOCDOC the_v2_networkstatus_is_dirty */ +/** Do we need to regenerate our v2 networkstatus document when somebody asks + * for it? */ static time_t the_v2_networkstatus_is_dirty = 1; /** Most recently generated encoded signed v1 directory. (v1 auth dirservers @@ -1224,9 +1226,12 @@ directory_too_idle_to_fetch_descriptors(or_options_t *options, time_t now) /* Used only by non-v1-auth dirservers: The v1 directory and * runningrouters we'll serve when requested. */ -/* DOCDOC cached_directory */ + +/** The v1 directory we'll serve (as a cache or as an authority) if + * requested. */ static cached_dir_t *cached_directory = NULL; -/* DOCDOC cached_runningrouters */ +/** The v1 runningrouters document we'll serve (as a cache or as an authority) + * if requested. */ static cached_dir_t cached_runningrouters = { NULL, NULL, 0, 0, 0, -1 }; /** Used for other dirservers' v2 network statuses. Map from hexdigest to @@ -1640,7 +1645,7 @@ should_generate_v2_networkstatus(void) /* Thresholds for server performance: set by * dirserv_compute_performance_thresholds, and used by * generate_v2_networkstatus */ -/* XXXX stick these all in a struct. */ + /* DOCDOC stable_uptime */ static uint32_t stable_uptime = 0; /* start at a safe value */ /* DOCDOC stable_mtbf */ diff --git a/src/or/hibernate.c b/src/or/hibernate.c index fed92dde85..4195fed654 100644 --- a/src/or/hibernate.c +++ b/src/or/hibernate.c @@ -103,13 +103,12 @@ static time_t interval_wakeup_time = 0; static uint64_t expected_bandwidth_usage = 0; /** What unit are we using for our accounting? */ static time_unit_t cfg_unit = UNIT_MONTH; + /** How many days,hours,minutes into each unit does our accounting interval * start? */ -static int cfg_start_day = 0; -/* DOCDOC cfg_start_hour */ -static int cfg_start_hour = 0; -/* DOCDOC cfg_start_min */ -static int cfg_start_min = 0; +static int cfg_start_day = 0, + cfg_start_hour = 0, + cfg_start_min = 0; static void reset_accounting(time_t now); static int read_bandwidth_usage(void); diff --git a/src/or/main.c b/src/or/main.c index dda0cf257e..c8d76bdae1 100644 --- a/src/or/main.c +++ b/src/or/main.c @@ -52,9 +52,9 @@ static int stats_prev_global_read_bucket; * (used to determine how many bytes we've written). */ static int stats_prev_global_write_bucket; /* XXX we might want to keep stats about global_relayed_*_bucket too. Or not.*/ -/** How many bytes have we read/written since we started the process? */ +/** How many bytes have we read since we started the process? */ static uint64_t stats_n_bytes_read = 0; -/* DOCDOC stats_n_bytes_written */ +/** How many bytes have we written since we started the process? */ static uint64_t stats_n_bytes_written = 0; /** What time did this process start up? */ time_t time_of_process_start = 0; @@ -1861,7 +1861,9 @@ tor_init(int argc, char *argv[]) return 0; } -/* DOCDOC lockfile */ +/** A lockfile structure, used to prevent two Tors from messing with the + * data directory at once. If this variable is non-NULL, we're holding + * the lockfile. */ static tor_lockfile_t *lockfile = NULL; /** Try to grab the lock file described in options, if we do not diff --git a/src/or/networkstatus.c b/src/or/networkstatus.c index 7b74dab51f..d7a2520278 100644 --- a/src/or/networkstatus.c +++ b/src/or/networkstatus.c @@ -39,11 +39,14 @@ static networkstatus_t *current_consensus = NULL; /** A v3 consensus networkstatus that we've received, but which we don't * have enough certificates to be happy about. */ static networkstatus_t *consensus_waiting_for_certs = NULL; -/* DOCDOC consensus_waiting_for_certs_body */ +/** The encoded version of consensus_waiting_for_certs. */ static char *consensus_waiting_for_certs_body = NULL; -/* DOCDOC consensus_waiting_for_certs_set_at */ +/** When did we set the current value of consensus_waiting_for_certs? If this + * is too recent, we shouldn't try to fetch a new consensus for a little while, + * to give ourselves time to get certificates for this one. */ static time_t consensus_waiting_for_certs_set_at = 0; -/* DOCDOC consensus_waiting_for_certs_dl_failed */ +/** Set to 1 if we've been holding on to consensus_waiting_for_certs so long + * that we should treat it as maybe being bad. */ static int consensus_waiting_for_certs_dl_failed = 0; /** The last time we tried to download a networkstatus, or 0 for "never". We diff --git a/src/or/or.h b/src/or/or.h index ff578b0b4b..1082a79c6a 100644 --- a/src/or/or.h +++ b/src/or/or.h @@ -2527,11 +2527,17 @@ typedef struct { * count of how many client addresses have contacted us so that we can help * the bridge authority guess which countries have blocked access to us. */ int BridgeRecordUsageByCountry; + #ifdef ENABLE_GEOIP_STATS - /* DOCDOC all of these. */ + /** If true, and Tor is built with GEOIP_STATS support, and we're a + * directory, record how many directory requests we get from each country. */ int DirRecordUsageByCountry; + /** Round all GeoIP results to the next multiple of this value, to avoid + * leaking information. */ int DirRecordUsageGranularity; + /** Time interval: purge geoip stats after this long. */ int DirRecordUsageRetainIPs; + /** Time interval: Flush geoip data to disk this often. */ int DirRecordUsageSaveInterval; #endif diff --git a/src/or/relay.c b/src/or/relay.c index 12ec2648d2..75bbf4cd23 100644 --- a/src/or/relay.c +++ b/src/or/relay.c @@ -1163,13 +1163,17 @@ connection_edge_process_relay_cell(cell_t *cell, circuit_t *circ, return 0; /* for forward compatibility, don't kill the circuit */ } -/* DOCDOC stats_n_data_cells_packaged */ +/** How many relay_data cells have we built, ever? */ uint64_t stats_n_data_cells_packaged = 0; -/* DOCDOC stats_n_data_bytes_packaged */ +/** How many bytes of data have we put in relay_data cells have we built, + * ever? This would be RELAY_PAYLOAD_SIZE*stats_n_data_cells_packaged if + * every relay cell we ever sent were completely full of data. */ uint64_t stats_n_data_bytes_packaged = 0; -/* DOCDOC stats_n_data_cells_received */ +/** How many relay_data cells have we received, ever? */ uint64_t stats_n_data_cells_received = 0; -/* DOCDOC stats_n_data_bytes_received */ +/** How many bytes of data have we received relay_data cells, ever? This would + * be RELAY_PAYLOAD_SIZE*stats_n_data_cells_packaged if every relay cell we + * ever received were completely full of data. */ uint64_t stats_n_data_bytes_received = 0; /** While conn->inbuf has an entire relay payload of bytes on it, @@ -1430,7 +1434,7 @@ circuit_consider_sending_sendme(circuit_t *circ, crypt_path_t *layer_hint) /** The total number of cells we have allocated from the memory pool. */ static int total_cells_allocated = 0; -/* DOCDOC cell_pool */ +/** A memory pool to allocate packed_cell_t objects. */ static mp_pool_t *cell_pool = NULL; /** Allocate structures to hold cells. */ diff --git a/src/or/router.c b/src/or/router.c index 79c5be65b5..ec36bdfe91 100644 --- a/src/or/router.c +++ b/src/or/router.c @@ -45,9 +45,11 @@ static crypto_pk_env_t *authority_signing_key = NULL; * authorities. */ static authority_cert_t *authority_key_certificate = NULL; -/* DOCDOC legacy_signing_key */ +/** For emergency V3 authority key migration: An extra signing key that we use + * with our old (obsolete) identity key for a while. */ static crypto_pk_env_t *legacy_signing_key = NULL; -/* DOCDOC legacy_key_certificate */ +/** For emergency V3 authority key migration: An extra certificate to + * authenticate legacy_signing_key with our obsolete identity key.*/ static authority_cert_t *legacy_key_certificate = NULL; /* (Note that v3 authorities also have a separate "authority identity key", @@ -1606,8 +1608,7 @@ router_guess_address_from_dir_headers(uint32_t *guess) return -1; } -/* DOCDOC tor_svn_revision */ -extern const char tor_svn_revision[]; /* from main.c */ +extern const char tor_svn_revision[]; /* from tor_main.c */ /** Set platform (max length len) to a NUL-terminated short * string describing the version of Tor and the operating system we're diff --git a/src/or/routerparse.c b/src/or/routerparse.c index 46eaceadb8..3497ffbeef 100644 --- a/src/or/routerparse.c +++ b/src/or/routerparse.c @@ -321,6 +321,7 @@ static token_rule_t dir_token_table[] = { END_OF_TABLE }; +/** List of tokens common to V3 authority certificates and V3 consensuses. */ #define CERTIFICATE_MEMBERS \ T1("dir-key-certificate-version", K_DIR_KEY_CERTIFICATE_VERSION, \ GE(1), NO_OBJ ), \ @@ -333,7 +334,7 @@ static token_rule_t dir_token_table[] = { NO_ARGS, NEED_OBJ), \ T01("dir-address", K_DIR_ADDRESS, GE(1), NO_OBJ), -/* DOCDOC dir_key_certificate_table */ +/** List of tokens allowable in V3 authority certificates. */ static token_rule_t dir_key_certificate_table[] = { CERTIFICATE_MEMBERS T1("fingerprint", K_FINGERPRINT, CONCAT_ARGS, NO_OBJ ), @@ -374,7 +375,7 @@ static token_rule_t client_keys_token_table[] = { END_OF_TABLE }; -/* DOCDOC networkstatus_token_table */ +/** List of tokens allowed in V3 networkstatus votes. */ static token_rule_t networkstatus_token_table[] = { T1("network-status-version", K_NETWORK_STATUS_VERSION, GE(1), NO_OBJ ), @@ -400,7 +401,8 @@ static token_rule_t networkstatus_token_table[] = { END_OF_TABLE }; -/* DOCDOC networkstatus_consensus_token_table */ + +/** List of tokens allowed in V3 networkstatus consensuses. */ static token_rule_t networkstatus_consensus_token_table[] = { T1("network-status-version", K_NETWORK_STATUS_VERSION, GE(1), NO_OBJ ), @@ -432,7 +434,7 @@ static token_rule_t networkstatus_vote_footer_token_table[] = { END_OF_TABLE }; -/* DOCDOC networkstatus_detached_signature_token_table */ +/** List of tokens allowable in detached networkstatus signature documents. */ static token_rule_t networkstatus_detached_signature_token_table[] = { T1_START("consensus-digest", K_CONSENSUS_DIGEST, GE(1), NO_OBJ ), T1("valid-after", K_VALID_AFTER, CONCAT_ARGS, NO_OBJ ), diff --git a/src/or/test.c b/src/or/test.c index 521d557a2e..a75d074163 100644 --- a/src/or/test.c +++ b/src/or/test.c @@ -6,7 +6,8 @@ const char test_c_id[] = "$Id$"; -/* DOCDOC tor_svn_revision */ +/* Ordinarily defined in tor_main.c; this bit is just here to provide one + * since we're not linking to tor_main.c */ const char tor_svn_revision[] = ""; /** @@ -2261,27 +2262,23 @@ test_util_digestset(void) smartlist_free(included); } -/* stop threads running at once. */ -/* DOCDOC _thread_test_mutex */ +/** mutex for thread test to stop the threads hitting data at the same time. */ static tor_mutex_t *_thread_test_mutex = NULL; -/* make sure that threads have to run at the same time. */ -/* DOCDOC _thread_test_start1 */ -static tor_mutex_t *_thread_test_start1 = NULL; -/* DOCDOC _thread_test_start2 */ -static tor_mutex_t *_thread_test_start2 = NULL; -/* DOCDOC _thread_test_strmap */ +/** mutexes for the thread test to make sure that the threads have to + * interleave somewhat. */ +static tor_mutex_t *_thread_test_start1 = NULL, + *_thread_test_start2 = NULL; +/** Shared strmap for the thread test. */ static strmap_t *_thread_test_strmap = NULL; -/* DOCDOC _thread1_name */ +/** The name of thread1 for the thread test */ static char *_thread1_name = NULL; -/* DOCDOC _thread2_name */ +/** The name of thread2 for the thread test */ static char *_thread2_name = NULL; static void _thread_test_func(void* _s) ATTR_NORETURN; -/* DOCDOC t1_count */ -static int t1_count = 0; -/* DOCDOC t2_count */ -static int t2_count = 0; +/** How many iterations have the threads in the unit test run? */ +static int t1_count = 0, t2_count = 0; /** Helper function for threading unit tests: This function runs in a * subthread. It grabs its own mutex (start1 or start2) to make sure that it @@ -3154,17 +3151,11 @@ test_dirutil(void) smartlist_free(sl); } -/* DOCDOC AUTHORITY_CERT_1 */ extern const char AUTHORITY_CERT_1[]; -/* DOCDOC AUTHORITY_SIGNKEY_1 */ extern const char AUTHORITY_SIGNKEY_1[]; -/* DOCDOC AUTHORITY_CERT_2 */ extern const char AUTHORITY_CERT_2[]; -/* DOCDOC AUTHORITY_SIGNKEY_2 */ extern const char AUTHORITY_SIGNKEY_2[]; -/* DOCDOC AUTHORITY_CERT_3 */ extern const char AUTHORITY_CERT_3[]; -/* DOCDOC AUTHORITY_SIGNKEY_3 */ extern const char AUTHORITY_SIGNKEY_3[]; /** Helper: Test that two networkstatus_voter_info_t do in fact represent the @@ -4608,17 +4599,27 @@ test_geoip(void) tor_free(s); } +/** For test_array. Declare an CLI-invocable off-by-default function in the + * unit tests, with function name and user-visible name x*/ #define DISABLED(x) { #x, x, 0, 0, 0 } +/** For test_array. Declare an CLI-invocable unit test function, with function + * name test_x(), and user-visible name x */ #define ENT(x) { #x, test_ ## x, 0, 0, 1 } +/** For test_array. Declare an CLI-invocable unit test function, with function + * name test_x_y(), and user-visible name + * x/y. This function will be treated as a subentry of x, + * so that invoking x from the CLI invokes this test too. */ #define SUBENT(x,y) { #x "/" #y, test_ ## x ## _ ## y, 1, 0, 1 } +/** An array of functions and information for all the unit tests we can run. */ static struct { - const char *test_name; - void (*test_fn)(void); - int is_subent; - int selected; - int is_default; -/* DOCDOC test_array */ + const char *test_name; /**< How does the user refer to this test from the + * command line? */ + void (*test_fn)(void); /**< What function is called to run this test? */ + int is_subent; /**< Is this a subentry of a bigger set of related tests? */ + int selected; /**< Are we planning to run this one? */ + int is_default; /**< If the user doesn't say what tests they want, do they + * get this function by default? */ } test_array[] = { ENT(buffers), ENT(crypto), diff --git a/src/or/test_data.c b/src/or/test_data.c index 7abd197a6c..cb8958a664 100644 --- a/src/or/test_data.c +++ b/src/or/test_data.c @@ -6,6 +6,7 @@ const char test_data_c_id[] = "$Id: /tor/trunk/src/or/test.c 13338 2007-06-10T19:13:32.101740Z nickm $"; +/** First of 3 example authority certificates for unit testing. */ const char AUTHORITY_CERT_1[] = "dir-key-certificate-version 3\n" "fingerprint D867ACF56A9D229B35C25F0090BC9867E906BE69\n" @@ -47,6 +48,7 @@ const char AUTHORITY_CERT_1[] = "eCHd0K8NrQK0ipVk/7zcPDKOPeo9Y5aj/f6X/pDHtb+Dd5sT+l82G/Tqy4DIYUYR\n" "-----END SIGNATURE-----\n"; +/** The private signing key for AUTHORITY_CERT_1 */ const char AUTHORITY_SIGNKEY_1[] = "-----BEGIN RSA PRIVATE KEY-----\n" "MIICWwIBAAKBgQCz0lCJ8rhLujVdzY6M6ZWp4iBAc0FxI79cff/pqp8GQAaWFZrs\n" @@ -64,6 +66,7 @@ const char AUTHORITY_SIGNKEY_1[] = "Yx4lqK0ca5IkTp3HevwnlWaJgbaOTUspCVshzJBhDA==\n" "-----END RSA PRIVATE KEY-----\n"; +/** Second of 3 example authority certificates for unit testing. */ const char AUTHORITY_CERT_2[] = "dir-key-certificate-version 3\n" "fingerprint 4D44AE0470B9E88FD4558EFEC82698FB33715400\n" @@ -99,6 +102,7 @@ const char AUTHORITY_CERT_2[] = "a8qDHR0tPS9/VkqTPcvUWCZeY3UiDeWPjoK1nea1pz6DHDWglKPx86a0amjjayZQ\n" "-----END SIGNATURE-----\n"; +/** The private signing key for AUTHORITY_CERT_2 */ const char AUTHORITY_SIGNKEY_2[] = "-----BEGIN RSA PRIVATE KEY-----\n" "MIICXgIBAAKBgQDrt3YK0LYd4qr4v1M38sGgDcNGwVLjDgYZzAXoixHES53iR1CZ\n" @@ -116,6 +120,7 @@ const char AUTHORITY_SIGNKEY_2[] = "rjZyXmEZS3oe7TRCDD28GAGMmxSDvNfOOpyn14ishEs5AQ==\n" "-----END RSA PRIVATE KEY-----\n"; +/** Third of 3 example authority certificates for unit testing. */ const char AUTHORITY_CERT_3[] = "dir-key-certificate-version 3\n" "fingerprint ED3719BF554DE9D7D59F5CA5A4F5AD121D020ED9\n" @@ -151,6 +156,7 @@ const char AUTHORITY_CERT_3[] = "pMc65FviIrc/Q5TUku6NNbCbnGll1599PvWuUzkG42lJ17V6psKHIsqGtVdHlCUc\n" "-----END SIGNATURE-----\n"; +/** The private signing key for AUTHORITY_CERT_3 */ const char AUTHORITY_SIGNKEY_3[] = "-----BEGIN RSA PRIVATE KEY-----\n" "MIICXgIBAAKBgQDa0mZVKt/AaM94rlDsnWEyVee6026tW8/NORT9kBtmftm8KYCi\n" diff --git a/src/or/tor_main.c b/src/or/tor_main.c index d4eee4291a..4f06f3fa90 100644 --- a/src/or/tor_main.c +++ b/src/or/tor_main.c @@ -6,7 +6,10 @@ const char tor_main_c_id[] = "$Id$"; -/* DOCDOC tor_svn_revision */ +/** String describing which Tor subversion repository version the source was + * built from. This string is generated by a bit of shell kludging int + * src/or/Makefile.am, and is usually right. + */ const char tor_svn_revision[] = #ifndef _MSC_VER #include "micro-revision.i"