Fix Sphinx Autodoc WARNING/ERROR in docs build

The docstrings here were all giving WARNINGs or ERRORs during the docs
build, and were generally making unappealing looking developer
documentation. I corrected the syntax and did what was neccessary to
make the build come out clean.

Change-Id: I74b00a7f125770b0468cff3bdf26d0d52cd054d7

ironic_python_agent/api/controllers/v1/base.py

@@ -45,7 +45,7 @@ class MultiType(wtypes.UserType):
 
     Used for validating that a value is an instance of one of the types.
 
-    :param *types: Variable-length list of types.
+    :param \*types: Variable-length list of types.
 
     """
     def __init__(self, *types):

ironic_python_agent/backoff.py

@@ -60,16 +60,19 @@ class BackOffLoopingCall(loopingcall.LoopingCallBase):
 
     :param initial_delay: delay before first running of function
     :param starting_interval: initial interval in seconds between calls to
-    function. When an error occurs and then a success, the interval is
+                              function. When an error occurs and then a
-    returned to starting_interval
+                              success, the interval is returned to
-    :param timeout: time in seconds before a LoopingCallTimeout is raised
+                              starting_interval
-    The call will never take longer than timeout, but may quit before timeout
+    :param timeout: time in seconds before a LoopingCallTimeout is raised.
+                    The call will never take longer than timeout, but may quit
+                    before timeout.
     :param max_interval: The maximum interval between calls during errors
     :param jitter: Used to vary when calls are actually run to avoid group of
-    calls all coming at the exact same time. Uses random.gauss(jitter,
+                   calls all coming at the exact same time. Uses
-    0.1), with jitter as the mean for the distribution. If set below .5,
+                   random.gauss(jitter, 0.1), with jitter as the mean for the
-    it can cause the calls to come more rapidly after each failure.
+                   distribution. If set below .5, it can cause the calls to
-    :raises: LoopingCallTimeout if time spent doing error retries would exceed
+                   come more rapidly after each failure.
+    :raises LoopingCallTimeout: if time spent doing error retries would exceed
                                 timeout.
     """
 

ironic_python_agent/extensions/clean.py

@@ -40,12 +40,14 @@ class CleanExtension(base.BaseAgentExtension):
     @base.async_command('execute_clean_step')
     def execute_clean_step(self, step, node, ports, clean_version=None,
                            **kwargs):
-        """Execute a clean step
+        """Execute a clean step.
+
         :param step: A clean step with 'step', 'priority' and 'interface' keys
         :param node: A dict representation of a node
         :param ports: A dict representation of ports attached to node
         :param clean_version: The clean version as returned by
-            _get_current_clean_version() at the beginning of cleaning/zapping
+                              _get_current_clean_version() at the beginning
+                              of cleaning/zapping
         :returns: a CommandResult object with command_result set to whatever
             the step returns.
         """

ironic_python_agent/hardware.py

@@ -163,30 +163,35 @@ class HardwareManager(object):
     def get_clean_steps(self, node, ports):
         """Get a list of clean steps with priority.
 
-        Returns a list of dicts of the following form:
+        Returns a list of steps. Each step is represeted by a dict::
-        {'step': the HardwareManager function to call.
+
-         'priority': the order steps will be run in. Ironic will sort all the
+          {
-            clean steps from all the drivers, with the largest priority
+           'step': the HardwareManager function to call.
-            step being run first. If priority is set to 0, the step will
+           'priority': the order steps will be run in. Ironic will sort all
-            not be run during cleaning, but may be run during zapping.
+                       the clean steps from all the drivers, with the largest
+                       priority step being run first. If priority is set to 0,
+                       the step will not be run during cleaning, but may be
+                       run during zapping.
            'reboot_requested': Whether the agent should request Ironic reboots
-            the node via the power driver after the operation completes.
+                               the node via the power driver after the
+                               operation completes.
           }
 
-        Note: multiple hardware managers may return the same step name. The
+        If multiple hardware managers return the same step name, the priority
-        priority of the step will be the largest priority of steps with
+        of the step will be the largest priority of steps with the same name.
-        the same name. The steps will be called using
+        The steps will be called using `hardware.dispatch_to_managers` and
-        `hardware.dispatch_to_managers` and handled by the best suited
+        handled by the best suited hardware manager. If you need a step to be
-        hardware manager. If you need a step to be executed by only your
+        executed by only your hardware manager, ensure it has a unique step
-        hardware manager, ensure it has a unique step name.
+        name.
 
         `node` and `ports` can be used by other hardware managers to further
         determine if a clean step is supported for the node.
 
         :param node: Ironic node object
         :param ports: list of Ironic port objects
-        :return: a default list of decommission steps, as a list of
+        :return: a list of cleaning steps, where each step is described as a
-        dictionaries
+                 dict as defined above
+
         """
         return [
             {