[tor-commits] [stem/master] Revised API docs for stem.util.enum

[atagar at torproject.org]

commit 907fb84cbc11d054718ba045ac7028676f4c1746
Author: Damian Johnson <atagar at torproject.org>
Date:   Sat Oct 27 10:37:21 2012 -0700

    Revised API docs for stem.util.enum
---
 docs/api.rst       |    9 ++++++---
 docs/contents.rst  |    2 ++
 docs/util/enum.rst |    5 +++++
 stem/util/enum.py  |   36 ++++++++++++++++++++----------------
 4 files changed, 33 insertions(+), 19 deletions(-)

diff --git a/docs/api.rst b/docs/api.rst
index 637c634..bb0d293 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -16,8 +16,11 @@ Descriptors
  * `stem.descriptor.extrainfo_descriptor <descriptor/extrainfo_descriptor.html>`_ - Relay and bridge extrainfo descriptors.
  * `stem.descriptor.networkstatus <descriptor/networkstatus.html>`_ - Network status documents which make up the Tor consensus.
  * `stem.descriptor.router_status_entry <descriptor/router_status_entry.html>`_ - Relay entries within a network status document.
+* `stem.descriptor.reader <descriptor/reader.html>`_ - Reads and parses descriptor files from disk.
+* `stem.descriptor.export <descriptor/export.html>`_ - Exports descriptors to other formats.
 
-* **Utilities**
- * `stem.descriptor.reader <descriptor/reader.html>`_ - Reads and parses descriptor files from disk.
- * `stem.descriptor.export <descriptor/export.html>`_ - Exports descriptors to other formats.
+Utilities
+---------
+
+* `stem.util.enum <util/enum.html>`_ - Enumeration class.
 
diff --git a/docs/contents.rst b/docs/contents.rst
index b142114..52cb6f4 100644
--- a/docs/contents.rst
+++ b/docs/contents.rst
@@ -20,3 +20,5 @@ Contents
    types/exit_policy
    types/version
 
+   util/enum
+
diff --git a/docs/util/enum.rst b/docs/util/enum.rst
new file mode 100644
index 0000000..b00dca4
--- /dev/null
+++ b/docs/util/enum.rst
@@ -0,0 +1,5 @@
+Enumerations
+============
+
+.. automodule:: stem.util.enum
+
diff --git a/stem/util/enum.py b/stem/util/enum.py
index 72c4443..9941de4 100644
--- a/stem/util/enum.py
+++ b/stem/util/enum.py
@@ -1,20 +1,22 @@
 """
 Basic enumeration, providing ordered types for collections. These can be
-constructed as simple type listings, ie:
+constructed as simple type listings...
 
 ::
 
-  >>> insects = Enum("ANT", "WASP", "LADYBUG", "FIREFLY")
+  >>> from stem.util import enum
+  >>> insects = enum.Enum("ANT", "WASP", "LADYBUG", "FIREFLY")
   >>> insects.ANT
   'Ant'
   >>> tuple(insects)
   ('Ant', 'Wasp', 'Ladybug', 'Firefly')
 
-with overwritten string counterparts:
+... or with overwritten string counterparts...
 
 ::
 
-  >>> pets = Enum(("DOG", "Skippy"), "CAT", ("FISH", "Nemo"))
+  >>> from stem.util import enum
+  >>> pets = enum.Enum(("DOG", "Skippy"), "CAT", ("FISH", "Nemo"))
   >>> pets.DOG
   'Skippy'
   >>> pets.CAT
@@ -25,6 +27,7 @@ with overwritten string counterparts:
 ::
 
   UppercaseEnum - Provides an enum instance with capitalized values.
+  
   Enum - Provides a basic, ordered  enumeration.
     |- keys - string representation of our enum keys
     |- index_of - indice of an enum value
@@ -38,19 +41,20 @@ import stem.util.str_tools
 
 def UppercaseEnum(*args):
   """
-  Provides an Enum instance where the values are identical to the keys. Since
-  the keys are uppercase by convention this means the values are too. For
-  instance...
+  Provides an :class:`~stem.util.enum.Enum` instance where the values are
+  identical to the keys. Since the keys are uppercase by convention this means
+  the values are too. For instance...
   
   ::
   
-    >>> runlevels = UppercaseEnum("DEBUG", "INFO", "NOTICE", "WARN", "ERROR")
+    >>> from stem.util import enum
+    >>> runlevels = enum.UppercaseEnum("DEBUG", "INFO", "NOTICE", "WARN", "ERROR")
     >>> runlevels.DEBUG
     'DEBUG'
   
   :param list args: enum keys to initialize with
   
-  :returns: :class:`stem.util.Enum` instance with the given keys
+  :returns: :class:`~stem.util.enum.Enum` instance with the given keys
   """
   
   return Enum(*[(v, v) for v in args])
@@ -82,7 +86,7 @@ class Enum(object):
     """
     Provides an ordered listing of the enumeration keys in this set.
     
-    :returns: tuple with our enum keys
+    :returns: **tuple** with our enum keys
     """
     
     return self._keys
@@ -93,9 +97,9 @@ class Enum(object):
     
     :param str value: entry to be looked up
     
-    :returns: integer index of the given entry
+    :returns: **int** index of the given entry
     
-    :raises: ValueError if no such element exists
+    :raises: **ValueError** if no such element exists
     """
     
     return self._values.index(value)
@@ -108,7 +112,7 @@ class Enum(object):
     
     :returns: enum value following the given entry
     
-    :raises: ValueError if no such element exists
+    :raises: **ValueError** if no such element exists
     """
     
     if not value in self._values:
@@ -127,7 +131,7 @@ class Enum(object):
     
     :returns: enum value proceeding the given entry
     
-    :raises: ValueError if no such element exists
+    :raises: **ValueError** if no such element exists
     """
     
     if not value in self._values:
@@ -144,9 +148,9 @@ class Enum(object):
     
     :param str item: key to be looked up
     
-    :returns: str with the value for the given key
+    :returns: **str** with the value for the given key
     
-    :raises: ValueError if the key doesn't exist
+    :raises: **ValueError** if the key doesn't exist
     """
     
     if item in self.__dict__: