docdoc and changelog for r18556

svn:r18566

3 files changed, 13 insertions, 2 deletions

diff --git a/ChangeLog b/ChangeLog
index 25f038ec1a..293c9a376a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -27,6 +27,9 @@ Changes in version 0.2.1.13-????? - 2009-02-??
   o Minor features:
     - On Linux, use the prctl call to re-enable core dumps when the user
       is option is set.
+    - New controller event NEWCONSENSUS that lists the networkstatus
+      lines for every recommended relay. Now controllers like Torflow
+      can keep up-to-date on which relays they should be using.
     - Update to the "January 23 2009" ip-to-country file.
 
 
diff --git a/src/or/control.c b/src/or/control.c
index 2f6adf6e6c..6a556ec30d 100644
--- a/src/or/control.c
+++ b/src/or/control.c
@@ -3517,8 +3517,10 @@ control_event_or_authdir_new_descriptor(const char *action,
   return 0;
 }
 
-/** Called when the routerstatus_ts <b>statuses</b> have changed: sends
- * an NS event to any controller that cares. */
+/** Helper function for NS-style events. Constructs and sends an event
+ * of type <b>event</b> with string <b>event_string</b> out of the set of
+ * networkstatuses <b>statuses</b>. Currently it is used for NS events
+ * and NEWCONSENSUS events. */
 static int
 control_event_networkstatus_changed_helper(smartlist_t *statuses,
                                            uint16_t event,
@@ -3553,12 +3555,16 @@ control_event_networkstatus_changed_helper(smartlist_t *statuses,
   return 0;
 }
 
+/** Called when the routerstatus_ts <b>statuses</b> have changed: sends
+ * an NS event to any controller that cares. */
 int
 control_event_networkstatus_changed(smartlist_t *statuses)
 {
   return control_event_networkstatus_changed_helper(statuses, EVENT_NS, "NS");
 }
 
+/** Called when we get a new consensus networkstatus. Sends a NEWCONSENSUS
+ * event consisting of an NS-style line for each relay in the consensus. */
 int
 control_event_newconsensus(const networkstatus_t *consensus)
 {
diff --git a/src/or/networkstatus.c b/src/or/networkstatus.c
index 81b1d07115..f9af470678 100644
--- a/src/or/networkstatus.c
+++ b/src/or/networkstatus.c
@@ -1318,6 +1318,8 @@ notify_control_networkstatus_changed(const networkstatus_t *old_c,
   if (old_c == new_c)
     return;
 
+  /* tell the controller exactly which relays are still listed, as well
+   * as what they're listed as */
   control_event_newconsensus(new_c);
 
   if (!old_c) {