[or-cvs] r12869: Add a bit of missing documentation. (in tor/trunk: . doc src/or)
nickm at seul.org
nickm at seul.org
Wed Dec 19 04:18:28 UTC 2007
Author: nickm
Date: 2007-12-18 23:18:28 -0500 (Tue, 18 Dec 2007)
New Revision: 12869
Modified:
tor/trunk/
tor/trunk/doc/tor.1.in
tor/trunk/src/or/or.h
tor/trunk/src/or/routerlist.c
Log:
r15560 at tombo: nickm | 2007-12-18 23:18:21 -0500
Add a bit of missing documentation.
Property changes on: tor/trunk
___________________________________________________________________
svk:merge ticket from /tor/trunk [r15560] on d9e39d38-0f13-419c-a857-e10a0ce2aa0c
Modified: tor/trunk/doc/tor.1.in
===================================================================
--- tor/trunk/doc/tor.1.in 2007-12-19 03:55:40 UTC (rev 12868)
+++ tor/trunk/doc/tor.1.in 2007-12-19 04:18:28 UTC (rev 12869)
@@ -718,6 +718,13 @@
in their regular router descriptors. Tor does not use this information for
anything itself; to save bandwidth, leave this option turned off.
(Default: 0).
+.LP
+.TP
+\fBFallbackNetworkstatusFile\fP \fIFILENAME\fP
+If Tor doesn't have a cached networkstatus file, it starts out uses
+this one instead. Even if this file is out of date, Tor can still use
+it to learn about directory mirrors, so it doesn't need to put load on
+the authorities. (Default: None).
.LP
.TP
Modified: tor/trunk/src/or/or.h
===================================================================
--- tor/trunk/src/or/or.h 2007-12-19 03:55:40 UTC (rev 12868)
+++ tor/trunk/src/or/or.h 2007-12-19 04:18:28 UTC (rev 12869)
@@ -1178,7 +1178,8 @@
SAVED_IN_JOURNAL
} saved_location_t;
-/** DOCDOC */
+/** Enumeration: what kind of downlaod schedule are we using for a given
+ * object? */
typedef enum {
DL_SCHED_GENERIC = 0,
DL_SCHED_CONSENSUS = 1,
@@ -1191,7 +1192,7 @@
* again? */
uint8_t n_download_failures; /**< Number of failures trying to download the
* most recent descriptor. */
- download_schedule_t schedule : 1;
+ download_schedule_t schedule : 8;
} download_status_t;
/** The max size we expect router descriptor annotations we create to
@@ -1462,12 +1463,15 @@
char *contact; /**< Contact information for this voter. */
char vote_digest[DIGEST_LEN]; /**< Digest of this voter's vote, as signed. */
- /* DOCDOC */
- char signing_key_digest[DIGEST_LEN]; /* This part is _not_ signed. */
- char *signature;
- int signature_len;
- unsigned int bad_signature : 1;
- unsigned int good_signature : 1;
+ /* Nothing from here on is signed. */
+ char signing_key_digest[DIGEST_LEN]; /**< Declared digest of signing key
+ * used by this voter. */
+ char *signature; /**< Signature from this voter. */
+ int signature_len; /**< Length of <b>signature</b> */
+ unsigned int bad_signature : 1; /**< Set to true if we've verified the sig
+ * as good. */
+ unsigned int good_signature : 1; /**< Set to true if we've tried to verify
+ * the sig, and we know it's bad. */
} networkstatus_voter_info_t;
/** A common structure to hold a v2 network status vote, or a v2 network
@@ -2309,10 +2313,12 @@
/** The number of intervals we think a consensus should be valid. */
int V3AuthNIntervalsValid;
- /** DOCDOC here and in tor.1 */
+ /** File to check for a consensus networkstatus, if we don't have one
+ * cached. */
char *FallbackNetworkstatusFile;
/** DOCDOC here and in tor.1 */
+ /**XXXX020 make this always on? */
int LearnAuthorityAddrFromCerts;
/** DOCDOC here and in tor.1 */
@@ -2636,10 +2642,15 @@
const char *get_torrc_fname(void);
char *get_datadir_fname2_suffix(const char *sub1, const char *sub2,
const char *suffix);
-/**DOCDOC*/
+/** Return a newly allocated string containing datadir/sub1. See
+ * get_datadir_fname2_suffix. */
#define get_datadir_fname(sub1) get_datadir_fname2_suffix((sub1), NULL, NULL)
+/** Return a newly allocated string containing datadir/sub1/sub2. See
+ * get_datadir_fname2_suffix. */
#define get_datadir_fname2(sub1,sub2) \
get_datadir_fname2_suffix((sub1), (sub2), NULL)
+/** Return a newly allocated string containing datadir/sub1suffix. See
+ * get_datadir_fname2_suffix. */
#define get_datadir_fname_suffix(sub1, suffix) \
get_datadir_fname2_suffix((sub1), NULL, (suffix))
@@ -3023,9 +3034,10 @@
get_options()->DirPort, time(NULL))
void download_status_reset(download_status_t *dls);
-/** DOCDOC */
static int download_status_is_ready(download_status_t *dls, time_t now,
int max_failures);
+/** Return true iff, as of <b>now</b>, the resource tracked by <b>dls</b> is
+ * ready to get its download reattempted. */
static INLINE int
download_status_is_ready(download_status_t *dls, time_t now,
int max_failures)
Modified: tor/trunk/src/or/routerlist.c
===================================================================
--- tor/trunk/src/or/routerlist.c 2007-12-19 03:55:40 UTC (rev 12868)
+++ tor/trunk/src/or/routerlist.c 2007-12-19 04:18:28 UTC (rev 12869)
@@ -2769,8 +2769,8 @@
}
/** Insert <b>ei</b> into the routerlist, or free it. Other arguments are
- * as for router_add_to_routerlist().
- * DOCDOC Inserted
+ * as for router_add_to_routerlist(). Return true iff we actually inserted
+ * it.
*/
int
router_add_extrainfo_to_routerlist(extrainfo_t *ei, const char **msg,
@@ -3962,7 +3962,8 @@
* enough directory info to build circuits that our old answer can no longer
* be trusted. */
static int need_to_update_have_min_dir_info = 1;
-/** DOCDOC */
+/** String describing what we're missing before we have enough directory
+ * info. */
static char dir_info_status[128] = "";
/** Return true iff we have enough networkstatus and router information to
@@ -3989,7 +3990,8 @@
need_to_update_have_min_dir_info = 1;
}
-/** DOCDOC */
+/** Return a string describing what we're missing before we have enough
+ * directory info. */
const char *
get_dir_info_status_string(void)
{
@@ -4166,14 +4168,13 @@
return 1;
}
-/** Check whether <b>ri</b> is a router compatible with the extrainfo document
+/** Check whether <b>ri</b> (a.k.a. sd) is a router compatible with the
+ * extrainfo document
* <b>ei</b>. If no router is compatible with <b>ei</b>, <b>ei</b> should be
* dropped. Return 0 for "compatible", return 1 for "reject, and inform
* whoever uploaded <b>ei</b>, and return -1 for "reject silently.". If
* <b>msg</b> is present, set *<b>msg</b> to a description of the
- * incompatibility (if any)
- *
- * DOCDOC sd. DOCDOC extrainfo_is_bogus.
+ * incompatibility (if any).
**/
int
routerinfo_incompatible_with_extrainfo(routerinfo_t *ri, extrainfo_t *ei,
More information about the tor-commits
mailing list