Add remaining docstrings

docs/sidecars.rst

@@ -3,7 +3,7 @@ Sidecars
 
 Use one ore more Sidecars to merge content from there into the APIfile.
 
-Sidecars are either **yaml** or **json** files.
+Sidecars are either *yaml* or *json* files.
 This is determined by the extension in the filename.
 
 The filename is a dot-separated path into the keys of the APIfile.

ffflash/inc/nodelist.py

@@ -5,6 +5,14 @@
 
 
 def _nodelist_fetch(ff):
+    '''
+    Determines if ``--nodelist`` was a file or a url, and tries to fetch it.
+    Validates nodelist to be json and to have the *version*, *nodes* and
+    *updated_at* keys.
+
+    :param ff: running :class:`ffflash.main.FFFlash` instance
+    :return: the unpickled nodelist or ``False``/``None`` on error
+    '''
     if not ff.access_for('nodelist'):
         return False
 
@@ -33,6 +41,14 @@ def _nodelist_fetch(ff):
 
 
 def _nodelist_count(ff, nodelist):
+    '''
+    Count online nodes and sum up their clients from a nodelist.
+
+    :param ff: running :class:`ffflash.main.FFFlash` instance
+    :param nodelist: nodelist from :meth:`_nodelist_fetch`, should contain a
+        list of dictionaries at the key *nodes*
+    :return: Tuple of counted nodes and clients
+    '''
     nodes, clients = 0, 0
     for node in nodelist.get('nodes', []):
         if node.get('status', {}).get('online', False):
@@ -47,6 +63,20 @@ def _nodelist_count(ff, nodelist):
 
 
 def _nodelist_dump(ff, nodes, clients):
+    '''
+    Store the counted numbers in the api-file.
+
+    Sets the key ``state`` . ``nodes`` with the node number.
+
+    Leaves ``state`` . ``description`` untouched, if any already present.
+    If empty, or the pattern ``\[[\d]+ Nodes, [\d]+ Clients\]`` is matched,
+    the numbers in the pattern will be replaced.
+
+    :param ff: running :class:`ffflash.main.FFFlash` instance
+    :param nodes: Number of online nodes
+    :param clients: Number of their clients
+    :return: ``True`` if :attr:`api` was modified else ``False``
+    '''
     if not ff.access_for('nodelist'):
         return False
 
@@ -69,6 +99,13 @@ def _nodelist_dump(ff, nodes, clients):
 
 
 def handle_nodelist(ff):
+    '''
+    Entry function to receive a ``--nodelist`` and store determined results
+    into both :attr:`api` and ``--rankfile`` (if specified).
+
+    :param ff: running :class:`ffflash.main.FFFlash` instance
+    :return: ``True`` if :attr:`api` was modified else ``False``
+    '''
     if not ff.access_for('nodelist'):
         return False
 

ffflash/inc/rankfile.py

@@ -1,5 +1,12 @@
 
 def handle_rankfile(ff, nodelist):
+    '''
+    Entry function gather results from a retrieved ``--nodelist``  to store it
+    into the ``--rankfile``.
+
+    :param ff: running :class:`ffflash.main.FFFlash` instance
+    :return: ``True`` if rankfile was modified else ``False``
+    '''
     if not ff.access_for('rankfile'):
         return False
     if not nodelist or not isinstance(nodelist, dict):

ffflash/inc/sidecars.py

@@ -5,6 +5,19 @@
 
 
 def _sidecar_path(ff, sc):
+    '''
+    Check passed sidecars for valid paths, format (*json* or *yaml*) and for
+    valid filenames (no double dots).
+
+    :param ff: running :class:`ffflash.main.FFFlash` instance
+    :param sc: sidecar as passed by user
+    :return: Tuple of either (``False``, ``None``, ``None``) on error or:
+
+        * normalized and full path to ``sc``
+        * unvalidated key-names into api-file
+        * ``True`` if ``sc`` is a *yaml* file, ``False`` if it's *json*
+
+    '''
     ff.log('handling sidecar {}'.format(sc))
 
     sidepath = check_file_location(sc)
@@ -36,6 +49,17 @@ def _sidecar_path(ff, sc):
 
 
 def _sidecar_load(ff, sidepath, fields, as_yaml):
+    '''
+    Loads content from ``sidepath`` if it exists, otherwise returns the values
+    from the :attr:`api` instead.
+    This is only done, if ``fields`` exist in :attr:`api`.
+
+    :param ff: running :class:`ffflash.main.FFFlash` instance
+    :param sidepath: full path to the sidecar
+    :param fields: key-names into api-file
+    :param as_yaml: load as *yaml* instead of *json*
+    :return: The loaded content of ``sidepath`` or ``False``/``None`` on error
+    '''
     if not ff.access_for('sidecars'):
         return False
 
@@ -56,6 +80,16 @@ def _sidecar_load(ff, sidepath, fields, as_yaml):
 
 
 def _sidecar_dump(ff, sidepath, content, fields, as_yaml):
+    '''
+    Stores ``content`` both in :attr:`api` and ``sidepath``.
+
+    :param ff: running :class:`ffflash.main.FFFlash` instance
+    :param sidepath: full path to the sidecar
+    :param content: the value to store into sidecar/api-file
+    :param fields: key-names into api-file
+    :param as_yaml: dump as *yaml* instead of *json*
+    :return: ``True`` if ``sidepath`` was modified else ``False``
+    '''
     if not ff.access_for('sidecars'):
         return False
 
@@ -72,6 +106,14 @@ def _sidecar_dump(ff, sidepath, content, fields, as_yaml):
 
 
 def handle_sidecars(ff):
+    '''
+    Entry function to handle passed ``--sidecars``. Validating locations, names
+    and content of sidecars. Generating them if necessary and update
+    :attr:`api`.
+
+    :param ff: running :class:`ffflash.main.FFFlash` instance
+    :return: ``True`` if any sidecar was modified else ``False``
+    '''
     if not ff.access_for('sidecars'):
         return False