Covering code with documentation

* Added __doc__ to all major functions
   and classes.

 Implements: blueprint covering-fuel-client-with-documentation
Change-Id: Iaf1952bd52e118c2801766c2c5ffb992de2bf1d2

fuelclient/cli/__init__.py

@@ -11,3 +11,9 @@
 #    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 #    License for the specific language governing permissions and limitations
 #    under the License.
+
+"""fuelclient.cli sub-module contains functionality of
+fuelclient command line interface
+
+
+"""

fuelclient/cli/actions/__init__.py

@@ -11,7 +11,11 @@
 #    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 #    License for the specific language governing permissions and limitations
 #    under the License.
+"""fuelclient.cli.actions sub-module contains files with action classes
+which implement command line interface logic
 
+All action classes must be added to action_tuple to be used by parser
+"""
 from fuelclient.cli.actions.deploy import DeployChangesAction
 from fuelclient.cli.actions.environment import EnvironmentAction
 from fuelclient.cli.actions.fact import DeploymentAction

fuelclient/cli/actions/base.py

@@ -24,8 +24,18 @@ from fuelclient.client import APIClient
 
 class Action(object):
     """Action class generalizes logic of action execution
-    method action_func  - entry point of parser
+    method action_func  - entry point of parser with parsed arguments
 
+    flag_func_map - is tuple of pairs ("flag", self.some_method) where
+    "flag" is name of argument which causes "some_method" to be called.
+    None is used as "flag" when method will be called without any flag.
+
+    serializer - is Serializer class instance which supposed to be the
+    only way to read and write to output or file system.
+
+    args - tuple of function calls of functions from arguments module,
+    is a manifest of all arguments used in action, and is used to initialize
+    argparse subparser of that action.
     """
     def __init__(self):
         # Mapping of flags to methods
@@ -45,6 +55,10 @@ class Action(object):
 
     @property
     def examples(self):
+        """examples property is concatenation of __doc__ strings from
+        methods in child action classes, and is added as epilog of help
+        output
+        """
         methods_with_docs = set(
             method
             for _, method in self.flag_func_map
@@ -63,6 +77,12 @@ class Action(object):
 
 
 def wrap(method, args, f):
+    """wrap - is second order function, purpose of which is to
+    generalize argument checking for methods in actions in form
+    of decorator with arguments.
+
+    'check_all' and 'check_any' are partial function of wrap.
+    """
     @wraps(f)
     def wrapped_f(self, params):
         if method(getattr(params, _arg) for _arg in args):
@@ -79,8 +99,16 @@ def wrap(method, args, f):
 
 
 def check_all(*args):
+    """check_all - decorator with arguments, which checks that
+    all arguments are given before running action method, if
+    not all arguments are given, it raises an ArgumentException.
+    """
     return partial(wrap, all, args)
 
 
 def check_any(*args):
+    """check_any - decorator with arguments, which checks that
+    at least one arguments is given before running action method,
+    if no arguments were given, it raises an ArgumentException.
+    """
     return partial(wrap, any, args)

fuelclient/cli/arguments.py

@@ -111,18 +111,6 @@ class SetAction(argparse.Action):
             setattr(namespace, self.dest, set(values))
 
 
-def get_serializer_arg(serialization_method):
-    return {
-        "args": ["--{0}".format(serialization_method)],
-        "params": {
-            "dest": serialization_method,
-            "action": "store_true",
-            "help": "prints only {0} to stdout".format(serialization_method),
-            "default": False
-        }
-    }
-
-
 def get_debug_arg():
     return {
         "args": ["--debug"],

fuelclient/cli/error.py

@@ -18,6 +18,8 @@ import urllib2
 
 
 def exit_with_error(message):
+    """exit_with_error - writes message to stderr and exits with exit code 1.
+    """
     sys.stderr.write(message + "\n")
     exit(1)
 
@@ -65,6 +67,8 @@ class ParserException(FuelClientException):
 
 
 def handle_exceptions(exc):
+    """handle_exceptions - exception handling manager.
+    """
     if isinstance(exc, urllib2.HTTPError):
         error_body = exc.read()
         exit_with_error("{0} {1}".format(
@@ -80,6 +84,9 @@ def handle_exceptions(exc):
 
 
 def exceptions_decorator(func):
+    """exceptions_decorator - is decorator which intercepts exceptions and
+    redirects them to handle_exceptions.
+    """
     @wraps(func)
     def wrapper(*args, **kwargs):
         try:

fuelclient/cli/formatting.py

@@ -27,7 +27,7 @@ from fuelclient.cli.error import exit_with_error
 
 
 def format_table(data, acceptable_keys=None, column_to_join=None):
-    """Format list of dicts to ascii table
+    """Format list of dicts to table in a string form
 
     :acceptable_keys list(str): list of keys for which to create table
                                 also specifies their order
@@ -70,6 +70,8 @@ def format_table(data, acceptable_keys=None, column_to_join=None):
 
 
 def quote_and_join(words):
+    """quote_and_join - performs listing of objects and returns string.
+    """
     words = list(words)
     if len(words) > 1:
         return '{0} and "{1}"'.format(
@@ -86,6 +88,9 @@ def quote_and_join(words):
 
 
 def get_bar_for_progress(full_width, progress):
+    """get_bar_for_progress - returns string with a width of 'full_width'
+    which illustrates specific progress value.
+    """
     number_of_equal_signs = int(
         math.ceil(progress * float(full_width - 2) / 100)
     )
@@ -97,6 +102,9 @@ def get_bar_for_progress(full_width, progress):
 
 
 def download_snapshot_with_progress_bar(url, directory=os.path.curdir):
+    """downloads file from specific 'url' with progress bar and save it
+    to some 'directory'.
+    """
     if not os.path.exists(directory):
         exit_with_error("Folder {0} doesn't exist.".format(directory))
     file_name = os.path.join(
@@ -127,6 +135,9 @@ def download_snapshot_with_progress_bar(url, directory=os.path.curdir):
 
 
 def print_deploy_progress(deploy_task):
+    """Receives 'deploy_task' and depending on terminal availability
+    starts progress printing routines with or without curses.
+    """
     try:
         terminal_screen = curses.initscr()
         print_deploy_progress_with_terminal(deploy_task, terminal_screen)

fuelclient/cli/parser.py

@@ -25,6 +25,10 @@ from fuelclient.cli.serializers import Serializer
 
 
 class Parser:
+    """Parser class - encapsulates argparse's ArgumentParser
+    and based on available actions, serializers and additional flags
+    populates it.
+    """
     def __init__(self):
         self.args = sys.argv
         self.parser = argparse.ArgumentParser(

fuelclient/cli/serializers.py

@@ -22,7 +22,9 @@ import yaml
 
 
 class Serializer(object):
-
+    """Serializer class - contains all logic responsible for
+    printing to stdout, reading and writing files to file system.
+    """
     serializers = {
         "json": {
             "w": lambda d: json.dumps(d, indent=4),

fuelclient/client.py

@@ -124,4 +124,6 @@ class Client(object):
             default_flow_style=False
         )
 
+# This line is single point of instantiation for 'Client' class,
+# which intended to implement Singleton design pattern.
 APIClient = Client()

fuelclient/objects/__init__.py

@@ -12,6 +12,9 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 
+"""fuelclient.objects sub-module contains classes that mirror
+functionality from nailgun objects.
+"""
 
 from fuelclient.objects.base import BaseObject
 from fuelclient.objects.environment import Environment

fuelclient/objects/base.py

@@ -17,7 +17,13 @@ from fuelclient.client import APIClient
 
 
 class BaseObject(object):
+    """BaseObject class - base class for fuelclient.objects object classes
 
+    'class_api_path' - url path to object handler on Nailgun server.
+    'instance_api_path' - url path template which formatted with object id
+    returns only one serialized object.
+    'connection' - 'Client' class instance from fuelclient.client
+    """
     class_api_path = None
     instance_api_path = None
     connection = APIClient