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

[atagar at torproject.org]

commit e4014bd0e70fc3af567f6e762d585127141279e6
Author: Damian Johnson <atagar at torproject.org>
Date:   Sat Oct 27 15:21:30 2012 -0700

    Revised API docs for stem.util.str_tools
---
 docs/api.rst            |    1 +
 docs/contents.rst       |    1 +
 docs/util/str_tools.rst |    5 +++++
 stem/util/str_tools.py  |   21 +++++++++++----------
 4 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/docs/api.rst b/docs/api.rst
index 01c929d..3296228 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -27,4 +27,5 @@ Utilities
 * `stem.util.conf <util/conf.html>`_ - Configuration file handling.
 * `stem.util.connection <util/connection.html>`_ - Connection and IP related utilities.
 * `stem.util.enum <util/enum.html>`_ - Enumeration class.
+* `stem.util.str_tools <util/str_tools.html>`_ - String utilities.
 
diff --git a/docs/contents.rst b/docs/contents.rst
index 4cfbe21..f937e77 100644
--- a/docs/contents.rst
+++ b/docs/contents.rst
@@ -23,4 +23,5 @@ Contents
    util/conf
    util/connection
    util/enum
+   util/str_tools
 
diff --git a/docs/util/str_tools.rst b/docs/util/str_tools.rst
new file mode 100644
index 0000000..4e15def
--- /dev/null
+++ b/docs/util/str_tools.rst
@@ -0,0 +1,5 @@
+String Utilities
+================
+
+.. automodule:: stem.util.str_tools
+
diff --git a/stem/util/str_tools.py b/stem/util/str_tools.py
index e0a6d3e..f444760 100644
--- a/stem/util/str_tools.py
+++ b/stem/util/str_tools.py
@@ -85,9 +85,9 @@ def get_size_label(byte_count, decimal = 0, is_long = False, is_bytes = True):
   :param int byte_count: number of bytes to be converted
   :param int decimal: number of decimal digits to be included
   :param bool is_long: expands units label
-  :param bool is_bytes: provides units in bytes if true, bits otherwise
+  :param bool is_bytes: provides units in bytes if **True**, bits otherwise
   
-  :returns: str with human readable representation of the size
+  :returns: **str** with human readable representation of the size
   """
   
   if is_bytes: return _get_label(SIZE_UNITS_BYTES, byte_count, decimal, is_long)
@@ -118,7 +118,7 @@ def get_time_label(seconds, decimal = 0, is_long = False):
   :param int decimal: number of decimal digits to be included
   :param bool is_long: expands units label
   
-  :returns: str with human readable representation of the time
+  :returns: **str** with human readable representation of the time
   """
   
   return _get_label(TIME_UNITS, seconds, decimal, is_long)
@@ -140,7 +140,7 @@ def get_time_labels(seconds, is_long = False):
   :param int seconds: number of seconds to be converted
   :param bool is_long: expands units label
   
-  :returns: list of strings with human readable representations of the time
+  :returns: **list** of strings with human readable representations of the time
   """
   
   time_labels = []
@@ -167,9 +167,9 @@ def get_short_time_label(seconds):
     
   :param int seconds: number of seconds to be converted
   
-  :returns: str with the short representation for the time
+  :returns: **str** with the short representation for the time
   
-  :raises: ValueError if the input is negative
+  :raises: **ValueError** if the input is negative
   """
   
   if seconds < 0:
@@ -207,9 +207,9 @@ def parse_short_time_label(label):
     
   :param str label: time entry to be parsed
   
-  :returns: int with the number of seconds represented by the label
+  :returns: **int** with the number of seconds represented by the label
   
-  :raises: ValueError if input is malformed
+  :raises: **ValueError** if input is malformed
   """
   
   days, hours, minutes, seconds = '0', '0', '0', '0'
@@ -240,10 +240,11 @@ def _get_label(units, count, decimal, is_long):
   Provides label corresponding to units of the highest significance in the
   provided set. This rounds down (ie, integer truncation after visible units).
   
-  :param tuple units: type of units to be used for conversion, containing (count_per_unit, short_label, long_label)
+  :param tuple units: type of units to be used for conversion, containing
+    (count_per_unit, short_label, long_label)
   :param int count: number of base units being converted
   :param int decimal: decimal precision of label
-  :param bool is_long: uses the long label if true, short label otherwise
+  :param bool is_long: uses the long label if **True&&, short label otherwise
   """
   
   # formatted string for the requested number of digits