[tor-commits] [stem/master] Converting stem.util.enum to reStructuredText

[atagar at torproject.org]

commit d5ef02b04eccebef5d5bbf89003431c0d41f1401
Author: Damian Johnson <atagar at torproject.org>
Date:   Tue Jun 5 19:33:10 2012 -0700

    Converting stem.util.enum to reStructuredText
---
 stem/util/enum.py |  113 ++++++++++++++++++++++++++---------------------------
 1 files changed, 56 insertions(+), 57 deletions(-)

diff --git a/stem/util/enum.py b/stem/util/enum.py
index ccc9590..af9ac27 100644
--- a/stem/util/enum.py
+++ b/stem/util/enum.py
@@ -1,39 +1,51 @@
 """
 Basic enumeration, providing ordered types for collections. These can be
 constructed as simple type listings, ie:
->>> insects = Enum("ANT", "WASP", "LADYBUG", "FIREFLY")
->>> insects.ANT
-'Ant'
->>> tuple(insects)
-('Ant', 'Wasp', 'Ladybug', 'Firefly')
+
+::
+
+  >>> insects = Enum("ANT", "WASP", "LADYBUG", "FIREFLY")
+  >>> insects.ANT
+  'Ant'
+  >>> tuple(insects)
+  ('Ant', 'Wasp', 'Ladybug', 'Firefly')
 
 with overwritten string counterparts:
->>> pets = Enum(("DOG", "Skippy"), "CAT", ("FISH", "Nemo"))
->>> pets.DOG
-'Skippy'
->>> pets.CAT
-'Cat'
 
-to_camel_case - converts a string to camel case
-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
-  |- next - provides the enum after a given enum value
-  |- previous - provides the enum before a given value
-  |- __getitem__ - provides the value for an enum key
-  +- __iter__ - iterator over our enum keys
+::
+
+  >>> pets = Enum(("DOG", "Skippy"), "CAT", ("FISH", "Nemo"))
+  >>> pets.DOG
+  'Skippy'
+  >>> pets.CAT
+  'Cat'
+
+**Module Overview:**
+
+::
+
+  to_camel_case - converts a string to camel case
+  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
+    |- next - provides the enum after a given enum value
+    |- previous - provides the enum before a given value
+    |- __getitem__ - provides the value for an enum key
+    +- __iter__ - iterator over our enum keys
 """
 
 def to_camel_case(label, word_divider = " "):
   """
   Converts the given string to camel case, ie:
-  >>> to_camel_case("I_LIKE_PEPPERJACK!")
-  'I Like Pepperjack!'
   
-  Arguments:
-    label (str)        - input string to be converted
-    word_divider (str) - string used to replace underscores
+  ::
+  
+    >>> to_camel_case("I_LIKE_PEPPERJACK!")
+    'I Like Pepperjack!'
+  
+  :param str label: input string to be converted
+  :param str word_divider: string used to replace underscores
   """
   
   words = []
@@ -50,15 +62,15 @@ def UppercaseEnum(*args):
   the keys are uppercase by convention this means the values are too. For
   instance...
   
-  >>> runlevels = UppercaseEnum("DEBUG", "INFO", "NOTICE", "WARN", "ERROR")
-  >>> runlevels.DEBUG
-  'DEBUG'
+  ::
+  
+    >>> runlevels = UppercaseEnum("DEBUG", "INFO", "NOTICE", "WARN", "ERROR")
+    >>> runlevels.DEBUG
+    'DEBUG'
   
-  Arguments:
-    args (str) - list of enum keys to initialize with
+  :param list args: enum keys to initialize with
   
-  Returns:
-    stem.util.Enum instance with the given keys
+  :returns: :class:`stem.util.Enum` instance with the given keys
   """
   
   return Enum(*[(v, v) for v in args])
@@ -90,8 +102,7 @@ class Enum:
     """
     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
@@ -100,14 +111,11 @@ class Enum:
     """
     Provides the index of the given value in the collection.
     
-    Arguments:
-      value (str) - entry to be looked up
+    :param str value: entry to be looked up
     
-    Returns:
-      integer index of the given entry
+    :returns: integer index of the given entry
     
-    Raises:
-      ValueError if no such element exists
+    :raises: ValueError if no such element exists
     """
     
     return self._values.index(value)
@@ -116,14 +124,11 @@ class Enum:
     """
     Provides the next enumeration after the given value.
     
-    Arguments:
-      value (str) - enumeration for which to get the next entry
+    :param str value: enumeration for which to get the next entry
     
-    Returns:
-      enum value following the given entry
+    :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:
@@ -136,14 +141,11 @@ class Enum:
     """
     Provides the previous enumeration before the given value.
     
-    Arguments:
-      value (str) - enumeration for which to get the previous entry
+    :param str value: enumeration for which to get the previous entry
     
-    Returns:
-      enum value proceeding the given entry
+    :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:
@@ -156,14 +158,11 @@ class Enum:
     """
     Provides the values for the given key.
     
-    Arguments:
-      item (str) - key to be looked up
+    :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__: