Fix doc strings for text_helpers (except color stuff)

Thanks to Plamen for hint in review

diff --git a/src/text_helpers.py b/src/text_helpers.py
index 89f60a7..d60f165 100644 (file)
--- a/src/text_helpers.py
+++ b/src/text_helpers.py
@@ -19,10 +19,25 @@
 # Copyright (c) 2016-2018 Intra2net AG <info@intra2net.com>
 
 """
-Functions for printing colored text using ANSI escape sequences
 
-Not sure whether to save this as text_helpers.py or a shell_helpers.py or some
-other. Let's see what else could be added to any of those.
+SUMMARY
+------------------------------------------------------
+Functions for improving textual output.
+
+Copyright: 2015 Intra2net AG
+
+
+CONTENTS
+------------------------------------------------------
+This module has two parts. Part 1 includes:
+
+- head_and_tail: shows the first few and last few elements of an iterable that
+                 could potentially be pretty long
+- size_str: textual representation of data size
+
+Part2 contains functions for coloring text, a poor-man's version of other
+modules like :py:mod:`colorclass` (which is now also available on Intra2net
+systems)
 
 Functions might cause trouble when combined, e.g.::
 
@@ -31,16 +46,13 @@ Functions might cause trouble when combined, e.g.::
 will show the text "and green" not in bold. May have to try using specific
 end-of-color or end-of-style escape sequences instead of 0 (reset-everything).
 
-See also: python package colorclass, a more professional version of this.
 
-Color unrelated functions:
-- head_and_tail: shows the first few and last few elements of an iterable that
-                 could potentially be pretty long
-- size_str: textual representation of data size
+.. seealso:: http://stackoverflow.com/questions/287871/print-in-terminal-with-colors-using-python
+.. seealso:: https://en.wikipedia.org/wiki/ANSI_escape_code
 
-References:
-* http://stackoverflow.com/questions/287871/print-in-terminal-with-colors-using-python
-* https://en.wikipedia.org/wiki/ANSI_escape_code
+
+INTERFACE
+------------------------------------------------------
 """
 
 try:
@@ -57,16 +69,18 @@ from sys import stdout
 
 def head_and_tail(iterable, n_head=20, n_tail=20, n_elems=None,
                   skip_elem="...(skipping {n_skipped} elements)..."):
-    """ convenient way to shorten a possibly very long iterable before printing
+    """
+    Convenient way to shorten a possibly very long iterable before printing.
 
     Will not modify short iterables, but for longer lists/tuples/... will only
     yield first few, then a message how many were skipped and the last few
 
     The iterable does not even have to have a `len(..)` method if argument
     `n_elems` is given. Only needs a `next(..)` method. However, for very long
-    iterables this will be faster if radnom element access is provided via []
+    iterables this will be faster if random element access is provided via []
 
     :param iterable: an iterable
+    :type iterable: anything that can be iterated over
     :param int n_head: number of starting elements to yield (optional)
     :param int n_tail: number of ending elements to yield (optional)
     :param int n_elems: number of elements in iterable; give this to avoid a
@@ -75,10 +89,12 @@ def head_and_tail(iterable, n_head=20, n_tail=20, n_elems=None,
                       once at most; None to not yield a skip replacement; if str
                       then it will be formatted; optional, defaults to string
                       with number of skipped elems
+    :type skip_elem: anything you like
+    :yields: `n_head+n_tail` elements from iterable plus the `skip_elem` (or
+             less if iterable is shorter than this).
 
-    ..seealso: :py:func:`slice`, py:func:`itertools.islice`
+    .. seealso:: :py:func:`slice`, :py:func:`itertools.islice`
     """
-
     if n_elems is None:
         n_elems = len(iterable)
 
@@ -115,12 +131,17 @@ def head_and_tail(iterable, n_head=20, n_tail=20, n_elems=None,
 
 
 def size_str(byte_number, is_diff=False):
-    """ round byte_number to something easily human-readable like '1.5 GB'
+    """
+    Create a human-readable text representation of a file size.
 
-    :param bool is_diff: set to True to include a '+' or '-' in output;
+    Rounds and shortens size to something easily human-readable like '1.5 GB'.
+
+    :param int byte_number: Number of bytes to express as text
+    :param bool is_diff: Set to True to include a '+' or '-' in output;
                          default: False
+    :returns: textual representation of data
+    :rtype: str
     """
-
     # constants
     units = '', 'k', 'M', 'G', 'T', 'P', 'E', 'Z', 'Y'
     factor = 1024