From dbedda6ae4320d93b0e1b139f09efe2c1dfafe9c Mon Sep 17 00:00:00 2001
From: David Lehman <dlehman@redhat.com>
Date: Tue, 17 Sep 2013 17:56:04 -0500
Subject: [PATCH 4/6] Convert to sphinx docstrings.

---
 blivet/formats/__init__.py | 94 ++++++++++++++++++++++++++++++++--------------
 1 file changed, 65 insertions(+), 29 deletions(-)

diff --git a/blivet/formats/__init__.py b/blivet/formats/__init__.py
index 67ac996..471d560 100644
--- a/blivet/formats/__init__.py
+++ b/blivet/formats/__init__.py
@@ -62,26 +62,19 @@ def get_default_filesystem_type():
     raise DeviceFormatError("None of %s is supported by your kernel" % ",".join(default_fstypes))
 
 def getFormat(fmt_type, *args, **kwargs):
-    """ Return a DeviceFormat instance based on fmt_type and args.
+    """ Return an instance of the appropriate DeviceFormat class.
 
-        Given a device format type and a set of constructor arguments,
-        return a DeviceFormat instance.
+        :param fmt_type: The name of the formatting type
+        :type fmt_type: str.
+        :return: the format instance
+        :rtype: :class:`DeviceFormat`
+        :raises: ValueError
 
-        Return None if no suitable format class is found.
+        .. note::
 
-        Arguments:
-
-            fmt_type -- the name of the format type (eg: 'ext3', 'swap')
-
-        Keyword Arguments:
-
-            The keyword arguments may vary according to the format type,
-            but here is the common set:
-
-            device -- path to the device on which the format resides
-            uuid -- the UUID of the (preexisting) formatted device
-            exists -- whether or not the format exists on the device            
-            
+            Any additional arguments will be passed on to the constructor for
+            the format class. See the various :class:`DeviceFormat` subclasses
+            for an exhaustive list of the arguments that can be passed.
     """
     fmt_class = get_device_format_class(fmt_type)
     fmt = None
@@ -105,8 +98,10 @@ def getFormat(fmt_type, *args, **kwargs):
 def collect_device_format_classes():
     """ Pick up all device format classes from this directory.
 
-        Note: Modules must call register_device_format(FormatClass) in
-              order for the format class to be picked up.
+        .. note::
+
+            Modules must call :func:`register_device_format` to make format
+            classes available to :func:`getFormat`.
     """
     dir = os.path.dirname(__file__)
     for module_file in os.listdir(dir):
@@ -122,7 +117,13 @@ def collect_device_format_classes():
                 log.debug(format_exc())
 
 def get_device_format_class(fmt_type):
-    """ Return an appropriate format class based on fmt_type. """
+    """ Return an appropriate format class.
+
+        :param fmt_type: The name of the format type.
+        :type fmt_type: str.
+        :returns: The chosen DeviceFormat class
+        :rtype: class.
+    """
     if not device_formats:
         collect_device_format_classes()
 
@@ -143,7 +144,12 @@ def get_device_format_class(fmt_type):
     return fmt
 
 class DeviceFormat(object):
-    """ Generic device format. """
+    """ Generic device format.
+
+        This represents the absence of recognized formatting. That could mean a
+        device is uninitialized, has had zeros written to it, or contains some
+        valid formatting that this module does not support.
+    """
     _type = None
     _name = _("Unknown")
     _udevTypes = []
@@ -163,14 +169,14 @@ class DeviceFormat(object):
     _ksMountpoint = None
 
     def __init__(self, *args, **kwargs):
-        """ Create a DeviceFormat instance.
-
-            Keyword Arguments:
-
-                device -- path to the underlying device
-                uuid -- this format's UUID
-                exists -- indicates whether this is an existing format
-
+        """ Instantiate a DeviceFormat.
+
+            :keyword device: The path to the device node.
+            :type device: str.
+            :keyword uuid: the formatting's UUID.
+            :type uuid: str.
+            :keyword exists: Whether the formatting exists. (default: False)
+            :raises: ValueError
         """
         self.device = kwargs.get("device")
         self.uuid = kwargs.get("uuid")
@@ -300,6 +306,18 @@ class DeviceFormat(object):
         return self._majorminor
 
     def create(self, *args, **kwargs):
+        """ Write the formatting to the specified block device.
+
+            :keyword device: path to device node
+            :type device: str.
+            :raises: FormatCreateError
+            :returns: None.
+
+            .. :note::
+
+                If a device node path is passed to this method it will overwrite
+                any previously set value of this instance's "device" attribute.
+        """
         log_method_call(self, device=self.device,
                         type=self.type, status=self.status)
         # allow late specification of device path
@@ -311,6 +329,11 @@ class DeviceFormat(object):
             raise FormatCreateError("invalid device specification", self.device)
 
     def destroy(self, *args, **kwargs):
+        """ Remove the formatting from the associated block device.
+
+            :raises: FormatDestroyError
+            :returns: None.
+        """
         log_method_call(self, device=self.device,
                         type=self.type, status=self.status)
         try:
@@ -329,6 +352,18 @@ class DeviceFormat(object):
         self.exists = False
 
     def setup(self, *args, **kwargs):
+        """ Activate the formatting.
+
+            :keyword device: device node path
+            :type device: str.
+            :raises: FormatSetupError.
+            :returns: None.
+
+            .. :note::
+
+                If a device node path is passed to this method it will overwrite
+                any previously set value of this instance's "device" attribute.
+        """
         log_method_call(self, device=self.device,
                         type=self.type, status=self.status)
 
@@ -347,6 +382,7 @@ class DeviceFormat(object):
             raise FormatSetupError("invalid device specification")
 
     def teardown(self, *args, **kwargs):
+        """ Deactivate the formatting. """
         log_method_call(self, device=self.device,
                         type=self.type, status=self.status)
 
-- 
1.8.1.4

