[or-cvs] r8521: Document entry-guard related functions (in tor/trunk: . src/or)

[nickm at seul.org]

Author: nickm
Date: 2006-09-28 19:57:52 -0400 (Thu, 28 Sep 2006)
New Revision: 8521

Modified:
   tor/trunk/
   tor/trunk/src/or/circuitbuild.c
   tor/trunk/src/or/config.c
Log:
 r8975 at Kushana:  nickm | 2006-09-28 17:13:53 -0400
 Document entry-guard related functions



Property changes on: tor/trunk
___________________________________________________________________
 svk:merge ticket from /tor/trunk [r8975] on c95137ef-5f19-0410-b913-86e773d04f59

Modified: tor/trunk/src/or/circuitbuild.c
===================================================================
--- tor/trunk/src/or/circuitbuild.c	2006-09-28 23:57:49 UTC (rev 8520)
+++ tor/trunk/src/or/circuitbuild.c	2006-09-28 23:57:52 UTC (rev 8521)
@@ -33,7 +33,8 @@
   time_t unreachable_since; /**< 0 if we can connect to this guard, or the
                              * time at which we first noticed we couldn't
                              * connect to it. */
-  time_t last_attempted;
+  time_t last_attempted; /**< 0 if we can connect to this guard, or the time
+                          * at which we last failed to connect to it. */
 } entry_guard_t;
 
 /** A list of our chosen entry guards. */
@@ -1719,7 +1720,10 @@
   return state->chosen_exit->nickname;
 }
 
-/** DOCDOC */
+/** Check whether the entry guard <b>e</b> is usable, given the directory
+ * authorities' opinion about the rouer (stored in <b>ri</b>) and the user's
+ * configuration (in <b>options</b>).  Set <b>e</b>-&gt;bad_since
+ * accordingly. Return true iff the entry guard's status changs.*/
 static int
 entry_guard_set_status(entry_guard_t *e, routerinfo_t *ri,
                        or_options_t *options)
@@ -1760,7 +1764,8 @@
   return changed;
 }
 
-/** DOCDOC */
+/** Return true iff enought time has passed since we last tried connect to the
+ * unreachable guard <b>e</b> that we're willing to try again. */
 static int
 entry_is_time_to_retry(entry_guard_t *e, time_t now)
 {
@@ -1786,7 +1791,8 @@
  * - Listed as 'stable' or 'fast' by the current dirserver concensus,
  *   if demanded by <b>need_uptime</b> or <b>need_capacity</b>; and
  * - Allowed by our current ReachableAddresses config option.
- * DOCDOC assume_reachable.
+ * - Currently thought to be reachable by us (unless assume_reachable
+ *   is true).
  */
 static INLINE routerinfo_t *
 entry_is_live(entry_guard_t *e, int need_uptime, int need_capacity,
@@ -1837,6 +1843,8 @@
   return 0;
 }
 
+/** Dump a description of our list of entry guards to the log at level
+ * <b>severity</b> */
 static void
 log_entry_guards(int severity)
 {
@@ -2115,6 +2123,7 @@
  * config's EntryNodes first? */
 static int should_add_entry_nodes = 0;
 
+/** Called when the value of EntryNodes changes in our configuration. */
 void
 entry_nodes_should_be_added(void)
 {
@@ -2122,6 +2131,8 @@
   should_add_entry_nodes = 1;
 }
 
+/** Add all nodes in EntryNodes that aren't currently guard nodes to the list
+ * of guard nodes, at the front. */
 void
 entry_guards_prepend_from_config(void)
 {

Modified: tor/trunk/src/or/config.c
===================================================================
--- tor/trunk/src/or/config.c	2006-09-28 23:57:49 UTC (rev 8520)
+++ tor/trunk/src/or/config.c	2006-09-28 23:57:52 UTC (rev 8521)
@@ -317,9 +317,9 @@
 
   { "EntryGuard", "One of the nodes we have chosen as a fixed entry" },
   { "EntryGuardDownSince",
-    "The last entry guard has been down since this time." },
+    "The last entry guard has been unreachable since this time." },
   { "EntryGuardUnlistedSince",
-    "The last entry guard has been unlisted since this time." },
+    "The last entry guard has been unusable since this time." },
   { "LastWritten", "When was this state file last regenerated?" },
 
   { "TorVersion", "Which version of Tor generated this state file?" },