From b81e92cc565ee03f4f2c27af564d9a4101a1be6f Mon Sep 17 00:00:00 2001
From: brettlangdon <brett@blangdon.com>
Date: Fri, 27 Sep 2013 20:40:18 -0400
Subject: [PATCH] documentation is a good thing

---
 employ/commands/__init__.py | 30 +++++++++++++++--
 employ/managers/__init__.py | 65 ++++++++++++++++++++++++++++++++++++-
 2 files changed, 91 insertions(+), 4 deletions(-)

diff --git a/employ/commands/__init__.py b/employ/commands/__init__.py
index cde1840..4a5bf64 100644
--- a/employ/commands/__init__.py
+++ b/employ/commands/__init__.py
@@ -3,19 +3,43 @@ __path__ = extend_path(__path__, __name__)
 
 
 class Command(object):
+    """
+    Base Command class that all command plugins must inherit from.
+    """
     name = "command"
 
-    def run(self):
-        raise NotImplementedError()
+    def aggregate(self, results):
+        """
+        Method to join together the results of running :func:``command``
+
+        Method which must be overridden by child class.
 
-    def aggregate(self):
+        :param results: list of (status, stdout, stderr) for each
+            result of running :func:``command``
+        :type results: list
+        """
         raise NotImplementedError()
 
     def command(self):
+        """
+        Method to generate the command to run.
+
+        Method which must be override by child class.
+
+        :returns: str
+        """
         raise NotImplementedError()
 
     @classmethod
     def from_config(cls, config):
+        """
+        Helper classmethod to create an instance of :class:``employ.commands.Command``
+        from the provided config.
+
+        :param config: the config to get the :class:``employ.commands.Command`` instance
+        :type config: :class:``ConfigParser.RawConfigParser``
+        ::returns: :class:``employ.commands.Command``
+        """
         settings = {}
         if config.has_section(cls.name):
             settings = dict(config.items(cls.name))
diff --git a/employ/managers/__init__.py b/employ/managers/__init__.py
index 5cb8a5a..f74b95d 100644
--- a/employ/managers/__init__.py
+++ b/employ/managers/__init__.py
@@ -5,30 +5,93 @@ from employ.execptions import ExecutionError
 
 
 class Manager(object):
+    """
+    Base Manager class that all Manager plugins must inherit from.
+    """
     name = "manager"
 
     @classmethod
     def from_config(cls, config):
+        """
+        Helper classmethod used to create an instance of :class:``employ.managers.Manager``
+        from the provided `config`
+
+        :param config: the config to get the settings from
+        :type config: :class:``ConfigParser.RawConfigParser``
+        :returns: :class:``employ.managers.Manager``
+        """
         settings = {}
         if config.has_section(cls.name):
             settings = dict(config.items(cls.name))
         return cls(**settings)
 
     def setup_instances(self):
+        """
+        Method called to setup the required instances.
+
+        All children must implement this method.
+
+        The result of this method should be that all the required
+        instances are created/connected to.
+        """
         raise NotImplementedError()
 
-    __enter__ = setup_instances
+    def __enter__(self):
+        """
+        Used to call :func:``setup_instances`` when using in a context manager
+
+        with manager:
+            # instances are connected to
+        """
+        self.setup_instances()
 
     def cleanup_instances(self):
+        """
+        Method called to destroy/disconnect from instances.
+
+        All children must implement this method.
+
+        The result of this method should be that all instances are
+        disconnected or destroy.
+        """
         raise NotImplementedError()
 
     def __exit__(self, type, value, traceback):
+        """
+        Used to call :func:``cleanup_instances`` when using in a context manager
+
+        with manager:
+            # instances are available
+        # instances are destroyed
+        """
         self.cleanup_instances()
 
     def setup(self, script):
+        """
+        Execute `script` on all instances.
+
+        All children must implement this method.
+
+        :param script: filename of a local script to run on each instance
+        :type script: str
+        """
         raise NotImplementedError()
 
     def run(self, command):
+        """
+        Execute `command` on all instances.
+
+        All children must implement this method.
+
+        This method should execute `command.commad()` on all instances
+        as well as sending the results of all instances to `command.aggregate`
+
+        The results will be in the following format:
+            [(status, stdout, stderr), ...]
+
+        :param command: the command to run on the instances
+        :type command: :class:``employ.commands.Command`
+        """
         raise NotImplementedError()
 
     def validate_results(self, results, command):