documentation improvements

4 files changed, 63 insertions, 13 deletions

diff --git a/cliff/app.py b/cliff/app.py
index bd42477..6b1a851 100644
--- a/cliff/app.py
+++ b/cliff/app.py
@@ -15,6 +15,21 @@ LOG = logging.getLogger(__name__)
 
 class App(object):
     """Application base class.
+
+    :param description: one-liner explaining the program purpose
+    :paramtype description: str
+    :param version: application version number
+    :paramtype version: str
+    :param command_manager: plugin loader
+    :paramtype command_manager: cliff.commandmanager.CommandManager
+    :param stdin: Standard input stream
+    :paramtype stdin: readable I/O stream
+    :param stdout: Standard output stream
+    :paramtype stdout: writable I/O stream
+    :param stderr: Standard error output stream
+    :paramtype stderr: writable I/O stream
+    :param interactive_app_factory: callable to create an interactive application
+    :paramtype interactive_app_factory: cliff.interactive.InteractiveApp
     """
 
     NAME = os.path.splitext(os.path.basename(sys.argv[0]))[0]
@@ -24,21 +39,16 @@ class App(object):
     DEFAULT_VERBOSE_LEVEL = 1
 
     def __init__(self, description, version, command_manager,
-                 stdin=None, stdout=None, stderr=None):
+                 stdin=None, stdout=None, stderr=None,
+                 interactive_app_factory=InteractiveApp):
         """Initialize the application.
-
-        :param description: One liner explaining the program purpose
-        :param version: String containing the application version number
-        :param command_manager: A CommandManager instance
-        :param stdin: Standard input stream
-        :param stdout: Standard output stream
-        :param stderr: Standard error output stream
         """
         self.command_manager = command_manager
         self.command_manager.add_command('help', HelpCommand)
         self.stdin = stdin or sys.stdin
         self.stdout = stdout or sys.stdout
         self.stderr = stderr or sys.stderr
+        self.interactive_app_factory = interactive_app_factory
         self.parser = self.build_option_parser(description, version)
         self.interactive_mode = False
 
@@ -47,6 +57,11 @@ class App(object):
 
         Subclasses may override this method to extend
         the parser with more global options.
+
+        :param description: full description of the application
+        :paramtype description: str
+        :param version: version number for the application
+        :paramtype version: str
         """
         parser = argparse.ArgumentParser(
             description=description,
@@ -116,6 +131,9 @@ class App(object):
 
     def run(self, argv):
         """Equivalent to the main program for the application.
+
+        :param argv: input arguments and options
+        :paramtype argv: list of str
         """
         self.options, remainder = self.parser.parse_known_args(argv)
         self.configure_logging()
@@ -138,17 +156,27 @@ class App(object):
 
     def prepare_to_run_command(self, cmd):
         """Perform any preliminary work needed to run a command.
+
+        :param cmd: command processor being invoked
+        :paramtype cmd: cliff.command.Command
         """
         return
 
     def clean_up(self, cmd, result, err):
         """Hook run after a command is done to shutdown the app.
+
+        :param cmd: command processor being invoked
+        :paramtype cmd: cliff.command.Command
+        :param result: return value of cmd
+        :paramtype result: int
+        :param err: exception or None
+        :paramtype err: Exception
         """
         return
 
     def interact(self):
         self.interactive_mode = True
-        interpreter = InteractiveApp(self, self.command_manager, self.stdin, self.stdout)
+        interpreter = self.interactive_app_factory(self, self.command_manager, self.stdin, self.stdout)
         interpreter.prompt = '(%s) ' % self.NAME
         interpreter.cmdloop()
         return 0
diff --git a/cliff/command.py b/cliff/command.py
index 94c8e8e..7ff526e 100644
--- a/cliff/command.py
+++ b/cliff/command.py
@@ -6,6 +6,9 @@ import inspect
 
 class Command(object):
     """Base class for command plugins.
+
+    :param app: Application instance invoking the command.
+    :paramtype app: cliff.app.App
     """
     __metaclass__ = abc.ABCMeta
 
diff --git a/cliff/commandmanager.py b/cliff/commandmanager.py
index bb8bfe2..135714a 100644
--- a/cliff/commandmanager.py
+++ b/cliff/commandmanager.py
@@ -23,6 +23,10 @@ class EntryPointWrapper(object):
 
 class CommandManager(object):
     """Discovers commands and handles lookup based on argv data.
+
+    :param namespace: String containing the setuptools entrypoint namespace
+                      for the plugins to be loaded. For example,
+                      ``'cliff.formatter.list'``.
     """
     def __init__(self, namespace):
         self.commands = {}
diff --git a/cliff/interactive.py b/cliff/interactive.py
index 33aefc6..493235c 100644
--- a/cliff/interactive.py
+++ b/cliff/interactive.py
@@ -12,6 +12,20 @@ LOG = logging.getLogger(__name__)
 
 
 class InteractiveApp(cmd2.Cmd):
+    """Provides "interactive mode" features.
+
+    Refer to the cmd2_ and cmd_ documentation for details
+    about subclassing and configuring this class.
+
+    .. _cmd2: http://packages.python.org/cmd2/index.html
+    .. _cmd: http://docs.python.org/library/cmd.html
+
+    :param parent_app: The calling application (expected to be derived
+                       from :class:`cliff.main.App`).
+    :param command_manager: A :class:`cliff.commandmanager.CommandManager` instance.
+    :param stdin: Standard input stream
+    :param stdout: Standard output stream
+    """
 
     use_rawinput = True
     doc_header = "Shell commands (type help <topic>):"
@@ -32,10 +46,8 @@ class InteractiveApp(cmd2.Cmd):
         self.parent_app.run_subcommand(line_parts)
 
     def completedefault(self, text, line, begidx, endidx):
-        """Tab-completion for commands known to the command manager.
-
-        Does not handle options on the commands.
-        """
+        # Tab-completion for commands known to the command manager.
+        # Does not handle options on the commands.
         if not text:
             completions = sorted(n for n, v in self.command_manager)
         else:
@@ -75,6 +87,9 @@ class InteractiveApp(cmd2.Cmd):
         return
 
     def get_names(self):
+        # Override the base class version to filter out
+        # things that look like they should be hidden
+        # from the user.
         return [n
                 for n in cmd2.Cmd.get_names(self)
                 if not n.startswith('do__')