[tor-commits] [tor/master] Document choose_random_entry_impl() and populate_live_entry_guards().

[nickm at torproject.org]

commit 61629b4f6ccb06ec190c4078797fcb48d83208d5
Author: George Kadianakis <desnacked at riseup.net>
Date:   Sun Jun 15 19:02:35 2014 -0700

    Document choose_random_entry_impl() and populate_live_entry_guards().
---
 src/or/entrynodes.c |   40 +++++++++++++++++++++++++++++++++++++---
 1 file changed, 37 insertions(+), 3 deletions(-)

diff --git a/src/or/entrynodes.c b/src/or/entrynodes.c
index 360c738..3dcb8f7 100644
--- a/src/or/entrynodes.c
+++ b/src/or/entrynodes.c
@@ -997,8 +997,25 @@ choose_random_dirguard(dirinfo_type_t type)
   return choose_random_entry_impl(NULL, 1, type, NULL);
 }
 
-/* DOCDOCODC
-   Return 1 if we should choose a guard right away. */
+/** Filter <b>all_entry_guards</b> for usable entry guards and put them
+ * in <b>live_entry_guards</b>. We filter based on whether the node is
+ * currently alive, and on whether it satisfies the restrictions
+ * imposed by the other arguments of this function.
+ *
+ * We don't place more guards than NumEntryGuards in <b>live_entry_guards</b>.
+ *
+ * If <b>chosen_exit</b> is set, it contains the exit node of this
+ * circuit. Make sure to not use it or its family as an entry guard.
+ *
+ * If <b>need_uptime</b> is set, we are looking for a stable entry guard.
+ * if <b>need_capacity</b> is set, we are looking for a fast entry guard.
+ *
+ * The rest of the arguments are the same as in choose_random_entry_impl().
+ *
+ * Return 1 if we should choose a guard right away. Return 0 if we
+ * should try to add more nodes to our list before deciding on a
+ * guard.
+ */
 STATIC int
 populate_live_entry_guards(smartlist_t *live_entry_guards,
                            const smartlist_t *all_entry_guards,
@@ -1058,7 +1075,24 @@ populate_live_entry_guards(smartlist_t *live_entry_guards,
   return retval;
 }
 
-/** Helper for choose_random{entry,dirguard}. */
+/** Pick a node to be used as the entry guard of a circuit.
+ *
+ * If <b>state</b> is set, it contains the information we know about
+ * the upcoming circuit.
+ *
+ * If <b>for_directory</b> is set, we are looking for a directory guard.
+ *
+ * <b>dirinfo_type</b> contains the kind of directory information we
+ * are looking for in our node.
+ *
+ * If <b>n_options_out</b> is set, we set it to the number of
+ * candidate guard nodes we had before picking a specific guard node.
+ *
+ * On success, return the node that should be used as the entry guard
+ * of the circuit.  Return NULL if no such node could be found.
+ *
+ * Helper for choose_random{entry,dirguard}.
+*/
 static const node_t *
 choose_random_entry_impl(cpath_build_state_t *state, int for_directory,
                          dirinfo_type_t dirinfo_type, int *n_options_out)