Trivial documentation improvements.

3 files changed, 25 insertions, 14 deletions

diff --git a/src/or/circuitlist.c b/src/or/circuitlist.c
index b25f817d91..ab38b54985 100644
--- a/src/or/circuitlist.c
+++ b/src/or/circuitlist.c
@@ -562,7 +562,6 @@ circuit_get_global_list,(void))
   return global_circuitlist;
 }
 
-/** */
 /** Return a pointer to the global list of origin circuits. */
 smartlist_t *
 circuit_get_global_origin_circuit_list(void)
@@ -1758,17 +1757,17 @@ circuit_find_circuits_to_upgrade_from_guard_wait(void)
   if (! circuits_pending_other_guards ||
       smartlist_len(circuits_pending_other_guards)==0)
     return NULL;
-  /* Only if we have some origin circuiuts should we run the algorithm.
-   */
+  /* Only if we have some origin circuits should we run the algorithm. */
   if (!global_origin_circuit_list)
     return NULL;
 
   /* Okay; we can pass our circuit list to entrynodes.c.*/
   smartlist_t *result = smartlist_new();
-  int r = entry_guards_upgrade_waiting_circuits(get_guard_selection_info(),
-                                                global_origin_circuit_list,
-                                                result);
-  if (r && smartlist_len(result)) {
+  int circuits_upgraded  = entry_guards_upgrade_waiting_circuits(
+                                                 get_guard_selection_info(),
+                                                 global_origin_circuit_list,
+                                                 result);
+  if (circuits_upgraded && smartlist_len(result)) {
     return result;
   } else {
     smartlist_free(result);
diff --git a/src/or/entrynodes.c b/src/or/entrynodes.c
index 76070a3b7d..a28603d98d 100644
--- a/src/or/entrynodes.c
+++ b/src/or/entrynodes.c
@@ -142,7 +142,9 @@
 #include "transports.h"
 #include "statefile.h"
 
+/** A list of existing guard selection contexts. */
 static smartlist_t *guard_contexts = NULL;
+/** The currently enabled guard selection context. */
 static guard_selection_t *curr_guard_context = NULL;
 
 /** A value of 1 means that at least one context has changed,
@@ -593,7 +595,8 @@ choose_guard_selection(const or_options_t *options,
              "rest of the world.", (int)(exclude_frac * 100));
   }
 
-  /* Easy case: no previous selection */
+  /* Easy case: no previous selection. Just check if we are in restricted or
+     normal guard selection. */
   if (old_selection == NULL) {
     if (n_passing_filter >= meaningful_threshold_mid) {
       *type_out = GS_TYPE_NORMAL;
@@ -768,8 +771,9 @@ entry_guard_add_to_sample(guard_selection_t *gs,
 
 /**
  * Backend: adds a new sampled guard to <b>gs</b>, with given identity,
- * nickname, and ORPort.  rsa_id_digest and bridge_addrport are
- * optional, but we need one of them. nickname is optional.
+ * nickname, and ORPort.  rsa_id_digest and bridge_addrport are optional, but
+ * we need one of them. nickname is optional. The caller is responsible for
+ * maintaining the size limit of the SAMPLED_GUARDS set.
  */
 static entry_guard_t *
 entry_guard_add_to_sample_impl(guard_selection_t *gs,
@@ -2171,7 +2175,8 @@ entry_guards_all_primary_guards_are_down(guard_selection_t *gs)
 }
 
 /** Wrapper for entry_guard_has_higher_priority that compares the
- * guard-priorities of a pair of circuits.
+ * guard-priorities of a pair of circuits. Return 1 if <b>a</b> has higher
+ * priority than <b>b</b>.
  *
  * If a restriction is provided in <b>rst</b>, then do not consider
  * <b>a</b> to have higher priority if it violates the restriction.
@@ -4180,6 +4185,8 @@ choose_random_entry_impl(guard_selection_t *gs,
 }
 #endif
 
+/** Check the pathbias use success count of <b>node</b> and disable it if it
+ *  goes over our thresholds. */
 static void
 pathbias_check_use_success_count(entry_guard_t *node)
 {
@@ -4201,6 +4208,8 @@ pathbias_check_use_success_count(entry_guard_t *node)
   }
 }
 
+/** Check the pathbias close count of <b>node</b> and disable it if it goes
+ *  over our thresholds. */
 static void
 pathbias_check_close_success_count(entry_guard_t *node)
 {
diff --git a/src/or/entrynodes.h b/src/or/entrynodes.h
index 3250be1222..116e5abb8c 100644
--- a/src/or/entrynodes.h
+++ b/src/or/entrynodes.h
@@ -402,11 +402,14 @@ int entry_guard_pick_for_circuit(guard_selection_t *gs,
                                  entry_guard_restriction_t *rst,
                                  const node_t **chosen_node_out,
                                  circuit_guard_state_t **guard_state_out);
+
+/* We just connected to an entry guard. What should we do with the circuit? */
 typedef enum {
-  GUARD_USABLE_NEVER = -1,
-  GUARD_MAYBE_USABLE_LATER = 0,
-  GUARD_USABLE_NOW = 1,
+  GUARD_USABLE_NEVER = -1, /* Never use the circuit */
+  GUARD_MAYBE_USABLE_LATER = 0, /* Keep it. We might use it in the future */
+  GUARD_USABLE_NOW = 1, /* Use it right now */
 } guard_usable_t;
+
 guard_usable_t entry_guard_succeeded(circuit_guard_state_t **guard_state_p);
 void entry_guard_failed(circuit_guard_state_t **guard_state_p);
 void entry_guard_cancel(circuit_guard_state_t **guard_state_p);