Add docstrings for api/ tree

Does what it says.

Partial-Bug 1367915

Change-Id: Id1a718d652f6d98e6acb1d667f42d9c3cc82aef5

ironic_python_agent/api/app.py

@@ -19,6 +19,7 @@ from ironic_python_agent.api import config
 
 
 class AgentHook(hooks.PecanHook):
+    """Hook to attach agent instance to API requests."""
     def __init__(self, agent, *args, **kwargs):
         super(AgentHook, self).__init__(*args, **kwargs)
         self.agent = agent
@@ -28,12 +29,22 @@ class AgentHook(hooks.PecanHook):
 
 
 def get_pecan_config():
-    # Set up the pecan configuration
+    """Set up the pecan configuration.
+
+    :returns: pecan configuration object.
+    """
     filename = config.__file__.replace('.pyc', '.py')
     return pecan.configuration.conf_from_file(filename)
 
 
-def setup_app(pecan_config=None, extra_hooks=None, agent=None):
+def setup_app(pecan_config=None, agent=None):
+    """Set up the API app.
+
+    :param pecan_config: a pecan configuration object.
+    :param agent: an :class:`ironic_python_agent.agent.IronicPythonAgent`
+                  instance.
+    :returns: wsgi app object.
+    """
     app_hooks = [AgentHook(agent)]
 
     if not pecan_config:
@@ -53,6 +64,8 @@ def setup_app(pecan_config=None, extra_hooks=None, agent=None):
 
 
 class VersionSelectorApplication(object):
+    """WSGI application that handles multiple API versions."""
+
     def __init__(self, agent):
         pc = get_pecan_config()
         self.v1 = setup_app(pecan_config=pc, agent=agent)

ironic_python_agent/api/controllers/v1/command.py

@@ -22,6 +22,8 @@ from ironic_python_agent.api.controllers.v1 import base
 
 
 class CommandResult(base.APIBase):
+    """Object representing the result of a given command."""
+
     id = types.text
     command_name = types.text
     command_params = types.DictType(types.text, base.json_type)
@@ -31,6 +33,13 @@ class CommandResult(base.APIBase):
 
     @classmethod
     def from_result(cls, result):
+        """Convert a BaseCommandResult object to a CommandResult object.
+
+        :param result: a :class:`ironic_python_agent.extensions.base.
+                       BaseCommandResult` object.
+        :returns: a :class:`ironic_python_agent.api.controllers.v1.command.
+                  CommandResult` object.
+        """
         instance = cls()
         for field in ('id', 'command_name', 'command_params', 'command_status',
                       'command_error', 'command_result'):
@@ -39,10 +48,18 @@ class CommandResult(base.APIBase):
 
 
 class CommandResultList(base.APIBase):
+    """An object representing a list of CommandResult objects."""
     commands = [CommandResult]
 
     @classmethod
     def from_results(cls, results):
+        """Convert a list of BaseCommandResult objects to a CommandResultList.
+
+        :param results: a list of :class:`ironic_python_agent.extensions.base.
+                       BaseCommandResult` objects.
+        :returns: a :class:`ironic_python_agent.api.controllers.v1.command.
+                  CommandResultList` object.
+        """
         instance = cls()
         instance.commands = [CommandResult.from_result(result)
                              for result in results]
@@ -50,7 +67,7 @@ class CommandResultList(base.APIBase):
 
 
 class Command(base.APIBase):
-    """A command representation."""
+    """A representation of a command."""
     name = types.wsattr(types.text, mandatory=True)
     params = types.wsattr(base.MultiType(dict), mandatory=True)
 
@@ -60,12 +77,20 @@ class CommandController(rest.RestController):
 
     @wsme_pecan.wsexpose(CommandResultList)
     def get_all(self):
+        """Get all command results."""
         agent = pecan.request.agent
         results = agent.list_command_results()
         return CommandResultList.from_results(results)
 
     @wsme_pecan.wsexpose(CommandResult, types.text, types.text)
     def get_one(self, result_id, wait=None):
+        """Get a command result by ID.
+
+        :param result_id: the ID of the result to get.
+        :param wait: if 'true', block until the command completes.
+        :returns: a :class:`ironic_python_agent.api.controller.v1.command.
+                  CommandResult` object.
+        """
         agent = pecan.request.agent
         result = agent.get_command_result(result_id)
 
@@ -76,6 +101,14 @@ class CommandController(rest.RestController):
 
     @wsme_pecan.wsexpose(CommandResult, types.text, body=Command)
     def post(self, wait=None, command=None):
+        """Post a command for the agent to run.
+
+        :param wait: if 'true', block until the command completes.
+        :param command: the command to execute. If None, an InvalidCommandError
+                        will be returned.
+        :returns: a :class:`ironic_python_agent.api.controller.v1.command.
+                  CommandResult` object.
+        """
         # the POST body is always the last arg,
         # so command must be a kwarg here
         if command is None:

ironic_python_agent/api/controllers/v1/status.py

@@ -22,11 +22,20 @@ from ironic_python_agent.api.controllers.v1 import base
 
 
 class AgentStatus(base.APIBase):
+    """An object representing an agent instance's status."""
+
     started_at = base.MultiType(float)
     version = types.text
 
     @classmethod
     def from_agent_status(cls, status):
+        """Convert an object representing agent status to an AgentStatus.
+
+        :param status: An :class:`ironic_python_agent.agent.
+                       IronicPythonAgentStatus` object.
+        :returns: An :class:`ironic_python_agent.api.controllers.v1.status.
+                  AgentStatus` object.
+        """
         instance = cls()
         for field in ('started_at', 'version'):
             setattr(instance, field, getattr(status, field))
@@ -38,6 +47,7 @@ class StatusController(rest.RestController):
 
     @wsme_pecan.wsexpose(AgentStatus)
     def get_all(self):
+        """Get current status of the running agent."""
         agent = pecan.request.agent
         status = agent.get_status()
         return AgentStatus.from_agent_status(status)