[tor-commits] [stem/master] Rewording event descriptions

[atagar at torproject.org]

commit c29efb501b83d8f1cf740a9da58f42ebf073c406
Author: Damian Johnson <atagar at torproject.org>
Date:   Fri May 20 10:21:58 2016 -0700

    Rewording event descriptions
    
    Renaming the function to event_description() and adjusting our descriptions of
    events.
---
 stem/control.py                 |  4 +++-
 stem/settings.cfg               | 47 ++++++++++++++++++++---------------------
 test/unit/control/controller.py |  8 +++----
 3 files changed, 30 insertions(+), 29 deletions(-)

diff --git a/stem/control.py b/stem/control.py
index 0ed7e8d..a036144 100644
--- a/stem/control.py
+++ b/stem/control.py
@@ -66,6 +66,8 @@ If you're fine with allowing your script to raise exceptions then this can be mo
 
 ::
 
+  event_description - brief description of a tor event type
+
   Controller - General controller class intended for direct use
     | |- from_port - Provides a Controller based on a port connection.
     | +- from_socket_file - Provides a Controller based on a socket file connection.
@@ -476,7 +478,7 @@ def with_default(yields = False):
   return decorator
 
 
-def event_summary(event):
+def event_description(event):
   """
   Provides a description for Tor events.
 
diff --git a/stem/settings.cfg b/stem/settings.cfg
index a08a6db..3c8cec4 100644
--- a/stem/settings.cfg
+++ b/stem/settings.cfg
@@ -1,12 +1,9 @@
 ################################################################################
 #
-# Information related to tor configuration options...
+# Information related to tor configuration options and events...
 #
 #   * manual.important   Most commonly used configuration options.
 #   * manual.summary     Short summary describing the option.
-#
-# Tor and Nyx event descriptions...
-#
 #   * event.description  Descriptions for the events.
 #
 ################################################################################
@@ -366,34 +363,36 @@ manual.summary.TestingLinkKeySlop Time before expiration that we replace our ed2
 manual.summary.TestingAuthKeySlop Time before expiration that we replace our ed25519 authentication key
 manual.summary.TestingSigningKeySlop Time before expiration that we replace our ed25519 signing key
 
-event.description.debug Tor debug logging event.
-event.description.info Tor info logging event.
-event.description.notice Tor notice logging event.
-event.description.warn Tor warn logging event.
-event.description.err Tor error logging event.
+# Brief description of tor events
+
+event.description.debug Logging at the debug runlevel. This is low level, high volume information about tor's internals that generally isn't useful to users.
+event.description.info Logging at the info runlevel. This is low level information of important internal processes.
+event.description.notice Logging at the notice runlevel. This runlevel and above are shown to users by default, and includes general information the user should be aware of.
+event.description.warn Logging at the warning runlevel. These are problems the user should be aware of.
+event.description.err Logging at the error runlevel. These are critical issues that may prevent tor from working properly.
 event.description.nyx_debug Nyx debug logging event.
 event.description.nyx_info Nyx info logging event.
 event.description.nyx_notice Nyx notice logging event.
 event.description.nyx_warn Nyx warn logging event.
 event.description.nyx_error Nyx error logging event.
-event.description.circ Indicates that a circuit has changed.
-event.description.circ_minor Provides information about minor changes in our circuits.
-event.description.stream Indicates that a stream has changed.
-event.description.orconn Indicates a change in a relay connection.
+event.description.circ Indicates that a circuit we've established through the tor network has been created, changed, or closed.
+event.description.circ_minor Minor changes to our circuits, such as reuse of existing circuits for a different purpose.
+event.description.stream Communication over a circuit we've established. For instance, Firefox making a connection through tor.
+event.description.orconn Change in our connections as a relay.
 event.description.bw Event emitted every second with the bytes sent and received by tor.
 event.description.newdesc Indicates that a new descriptor is available.
-event.description.addrmap Indicates a new address mapping.
-event.description.authdir_newdescs Indicates that we just received new descriptors specific to directory authorities.
+event.description.addrmap New address mapping for our DNS cache.
+event.description.authdir_newdescs Indicates we just received a new descriptor. This is only used by directory authorities.
 event.description.descchanged Indicates that our descriptor has changed.
-event.description.ns Event for when our copy of the consensus has changed.
+event.description.ns Consensus information for an individual relay has changed. This could be due to receiving a new consensus or tor locally decides a relay is up or down.
 event.description.status_general Notification of a change in tor's state.
-event.description.status_client Notification of a change in tor's state.
-event.description.status_server Notification of a change in tor's state.
-event.description.guard Indicates that our guard relays have changed.
-event.description.stream_bw Event with the bytes sent and received by tor since the last such event on this stream.
-event.description.clients_seen Periodic event on bridge relays that provide a summary of our users.
-event.description.newconsensus Event for when we have a new consensus.
+event.description.status_client Notification of a change in tor's state as a client (ie user).
+event.description.status_server Notification of a change in tor's state as a relay.
+event.description.guard Indicates that the set of relays we use for our initial connection into the tor network (guards) have changed.
+event.description.stream_bw Event emitted every second with the bytes sent and received for a specific stream.
+event.description.clients_seen Periodic summary of the countries we've seen users connect from. This is only used by bridge relays.
+event.description.newconsensus Received a new hourly consensus of relays in the tor network.
 event.description.buildtimeout_set Indicates the timeout value for a circuit has changed.
-event.description.signal Indicates that tor has received and acted upon a signal being sent to the process.
-event.description.conf_changed Indicates that our configuration changed, either in a response to a SETCONF or RELOAD signal.
+event.description.signal Indicates that tor has received and acted upon a signal being sent to its process.
+event.description.conf_changed Indicates that our torrc configuration has changed. This could be in response to a SETCONF or RELOAD signal.
 
diff --git a/test/unit/control/controller.py b/test/unit/control/controller.py
index 1b61e4d..afde523 100644
--- a/test/unit/control/controller.py
+++ b/test/unit/control/controller.py
@@ -34,10 +34,10 @@ class TestControl(unittest.TestCase):
     with patch('stem.control.Controller.add_event_listener', Mock()):
       self.controller = Controller(socket)
 
-  def test_event_summary(self):
-    self.assertEqual('Tor debug logging event.', stem.control.event_summary('DEBUG'))
-    self.assertEqual('Event emitted every second with the bytes sent and received by tor.', stem.control.event_summary('BW'))
-    self.assertEqual('Event emitted every second with the bytes sent and received by tor.', stem.control.event_summary('bw'))
+  def test_event_description(self):
+    self.assertEqual('Tor debug logging event.', stem.control.event_description('DEBUG'))
+    self.assertEqual('Event emitted every second with the bytes sent and received by tor.', stem.control.event_description('BW'))
+    self.assertEqual('Event emitted every second with the bytes sent and received by tor.', stem.control.event_description('bw'))
 
   @patch('stem.control.Controller.get_info')
   def test_get_version(self, get_info_mock):