From b4e063018ae3e3f9706365b097274739e46fc7c5 Mon Sep 17 00:00:00 2001
From: David Lehman <dlehman@redhat.com>
Date: Wed, 18 Sep 2013 19:06:59 -0500
Subject: [PATCH 6/6] Update docstrings to use sphinx and improve content
 somewhat.

---
 blivet/dasd.py              |   3 -
 blivet/devicetree.py        |  33 +++++++---
 blivet/formats/__init__.py  |  15 +++--
 blivet/formats/biosboot.py  |  12 ++--
 blivet/formats/disklabel.py |  67 ++++++++++----------
 blivet/formats/dmraid.py    |  16 +++--
 blivet/formats/fs.py        | 146 +++++++++++++++++++++++++++++++-------------
 blivet/formats/luks.py      |  74 ++++++++++++++++------
 blivet/formats/lvmpv.py     |  47 ++++++++++----
 blivet/formats/mdraid.py    |  20 +++---
 blivet/formats/multipath.py |  15 ++---
 blivet/formats/prepboot.py  |  29 +++++++--
 blivet/formats/swap.py      |  60 ++++++++++++------
 blivet/iscsi.py             |   3 -
 14 files changed, 359 insertions(+), 181 deletions(-)

diff --git a/blivet/dasd.py b/blivet/dasd.py
index c2ec2e4..754e0b4 100644
--- a/blivet/dasd.py
+++ b/blivet/dasd.py
@@ -216,7 +216,4 @@ class DASD:
             self._completedCylinders += 1.0
             callback_data.set(self._completedCylinders / self.totalCylinders)
 
-# Create DASD singleton
-DASD = DASD()
-
 # vim:tw=78:ts=4:et:sw=4
diff --git a/blivet/devicetree.py b/blivet/devicetree.py
index 0770840..a071920 100644
--- a/blivet/devicetree.py
+++ b/blivet/devicetree.py
@@ -59,25 +59,38 @@ log = logging.getLogger("blivet")
 class DeviceTree(object):
     """ A quasi-tree that represents the devices in the system.
 
-        The tree contains a list of device instances, which does not
-        necessarily reflect the actual state of the system's devices.
-        DeviceActions are used to perform modifications to the tree,
-        except when initially populating the tree.
+        The tree contains a list of :class:`~.devices.StorageDevice` instances,
+        which does not necessarily reflect the actual state of the system's
+        devices. :class:`~.deviceaction.DeviceAction` is used to perform
+        modifications to the tree, except when initially populating the tree.
 
-        DeviceAction instances are registered, possibly causing the
-        addition or removal of Device instances to/from the tree. The
-        DeviceActions are all reversible up to the time their execute
-        method has been called.
+        :class:`~.deviceaction.DeviceAction` instances are registered, possibly
+        causing the addition or removal of :class:`~.devices.StorageDevice`
+        instances to/from the tree. A :class:`~.deviceaction.DeviceAction`
+        is reversible up to the time its 'execute' method is called.
 
         Only one action of any given type/object pair should exist for
         any given device at any given time.
 
-        DeviceAction instances can only be registered for leaf devices,
-        except for resize actions.
+        :class:`~.deviceaction.DeviceAction` instances can only be registered
+        for leaf devices, except for resize actions.
     """
 
     def __init__(self, conf=None, passphrase=None, luksDict=None,
                  iscsi=None, dasd=None):
+        """
+
+            :keyword conf: storage discovery configuration
+            :type conf: :class:`~.StorageDiscoveryConfig`
+            :keyword passphrase: default LUKS passphrase
+            :keyword luksDict: a dict with UUID keys and passphrase values
+            :type luksDict: dict
+            :keyword iscsi: ISCSI control object
+            :type iscsi: :class:`~.iscsi.iscsi`
+            :keyword dasd: DASD control object
+            :type dasd: :class:`~.dasd.DASD`
+
+        """
         self.reset(conf, passphrase, luksDict, iscsi, dasd)
 
     def reset(self, conf=None, passphrase=None, luksDict=None,
diff --git a/blivet/formats/__init__.py b/blivet/formats/__init__.py
index 471d560..06905ac 100644
--- a/blivet/formats/__init__.py
+++ b/blivet/formats/__init__.py
@@ -169,14 +169,21 @@ class DeviceFormat(object):
     _ksMountpoint = None
 
     def __init__(self, *args, **kwargs):
-        """ Instantiate a DeviceFormat.
-
+        """
             :keyword device: The path to the device node.
-            :type device: str.
+            :type device: str
             :keyword uuid: the formatting's UUID.
-            :type uuid: str.
+            :type uuid: str
             :keyword exists: Whether the formatting exists. (default: False)
             :raises: ValueError
+
+            .. note::
+
+                The 'device' kwarg is required for existing formats. For non-
+                existent formats, it is only necessary that the :attr:`device`
+                attribute be set before the :meth:`create` method runs. Note
+                that you can specify the device at the last moment by specifying
+                it via the 'device' kwarg to the :meth:`create` method.
         """
         self.device = kwargs.get("device")
         self.uuid = kwargs.get("uuid")
diff --git a/blivet/formats/biosboot.py b/blivet/formats/biosboot.py
index c3aef8d..d7a5836 100644
--- a/blivet/formats/biosboot.py
+++ b/blivet/formats/biosboot.py
@@ -38,13 +38,15 @@ class BIOSBoot(DeviceFormat):
     _minSize = 0.5                      # minimum size in MB
 
     def __init__(self, *args, **kwargs):
-        """ Create a BIOSBoot instance.
-
-            Keyword Arguments:
+        """
+            :keyword device: path to the block device node
+            :type device: str
+            :keyword exists: whether the formatting exists
+            :type exists: bool
 
-                device -- path to the underlying device
-                exists -- indicates whether this is an existing format
+            .. note::
 
+                The 'device' kwarg is required for existing formats.
         """
         DeviceFormat.__init__(self, *args, **kwargs)
 
diff --git a/blivet/formats/disklabel.py b/blivet/formats/disklabel.py
index 90b73f3..d420ece 100644
--- a/blivet/formats/disklabel.py
+++ b/blivet/formats/disklabel.py
@@ -47,18 +47,20 @@ class DiskLabel(DeviceFormat):
     _supported = False                 # is supported
 
     def __init__(self, *args, **kwargs):
-        """ Create a DiskLabel instance.
-
-            Keyword Arguments:
-
-                labelType -- type of disklabel to create
-                device -- path to the underlying device
-                exists -- indicates whether this is an existing format
-
+        """
+            :keyword device: full path to the block device node (required)
+            :type device: str
+            :keyword labelType: type of disklabel to create
+            :type labelType: str
+            :keyword exists: whether the formatting exists
+            :type exists: bool
         """
         log_method_call(self, *args, **kwargs)
         DeviceFormat.__init__(self, *args, **kwargs)
 
+        if not self.device:
+            raise ValueError("DiskLabel requires a valid device path")
+
         if not self.exists:
             self._labelType = kwargs.get("labelType", "msdos")
         else:
@@ -233,25 +235,6 @@ class DiskLabel(DeviceFormat):
         """ Device status. """
         return False
 
-    def setup(self, *args, **kwargs):
-        """ Open, or set up, a device. """
-        log_method_call(self, device=self.device,
-                        type=self.type, status=self.status)
-        if not self.exists:
-            raise DeviceFormatError("format has not been created")
-
-        if self.status:
-            return
-
-        DeviceFormat.setup(self, *args, **kwargs)
-
-    def teardown(self, *args, **kwargs):
-        """ Close, or tear down, a device. """
-        log_method_call(self, device=self.device,
-                        type=self.type, status=self.status)
-        if not self.exists:
-            raise DeviceFormatError("format has not been created")
-
     def create(self, *args, **kwargs):
         """ Create the device. """
         log_method_call(self, device=self.device,
@@ -307,10 +290,21 @@ class DiskLabel(DeviceFormat):
         else:
             self.updateOrigPartedDisk()
 
-    def addPartition(self, *args, **kwargs):
-        partition = kwargs.get("partition", None)
-        if not partition:
-            partition = args[0]
+    def addPartition(self, partition, constraint=None):
+        """ Add a partition to the disklabel.
+
+            :param partition: partition from which to get geom, type (required)
+            :type partition: parted.Partition.
+            :keyword constraint: constraint to use
+            :type constraint: parted.Constraint.
+
+            .. note::
+
+                This does not add the :class:`parted.Partition` instance you
+                pass in. The geometry and type are taken from that instance and
+                used to create a new :class:`parted.Partition` to add to the
+                disklabel.
+        """
         geometry = partition.geometry
         constraint = kwargs.get("constraint", None)
         if not constraint and len(args) > 1:
@@ -325,6 +319,17 @@ class DiskLabel(DeviceFormat):
                                      constraint=constraint)
 
     def removePartition(self, partition):
+        """ Remove a partition from the disklabel.
+
+            :param partition: the partition to remove
+            :type partition: parted.Partition.
+
+            .. note::
+
+                Unlike :meth:`addPartition`, the actual partition instance
+                passed is what will be removed from the disklabel.
+
+        """
         self.partedDisk.removePartition(partition)
 
     @property
diff --git a/blivet/formats/dmraid.py b/blivet/formats/dmraid.py
index 2bf4567..e7d97b8 100644
--- a/blivet/formats/dmraid.py
+++ b/blivet/formats/dmraid.py
@@ -60,15 +60,13 @@ class DMRaidMember(DeviceFormat):
     _hidden = True                      # hide devices with this formatting?
 
     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
-
-            On initialization this format is like DeviceFormat
+        """
+                :keyword device: path to the underlying device (required)
+                :type device: str
+                :keyword uuid: this format's UUID
+                :type uuid: str
+                :keyword exists: whether this is an existing format
+                :type exists: bool
 
         """
         log_method_call(self, *args, **kwargs)
diff --git a/blivet/formats/fs.py b/blivet/formats/fs.py
index 13896c9..435f1c1 100644
--- a/blivet/formats/fs.py
+++ b/blivet/formats/fs.py
@@ -112,7 +112,7 @@ def fsConfigFromFile(config_file):
     fs_configs[fs_attrs['type']] = fs_attrs
 
 class FS(DeviceFormat):
-    """ Filesystem class. """
+    """ Filesystem base class. """
     _type = "Abstract Filesystem Class"  # fs type name
     _mountType = None                    # like _type but for passing to mount
     _name = None
@@ -132,18 +132,25 @@ class FS(DeviceFormat):
     _fsProfileSpecifier = None           # mkfs option specifying fsprofile
 
     def __init__(self, *args, **kwargs):
-        """ Create a FS instance.
-
-            Keyword Args:
-
-                device -- path to the device containing the filesystem
-                mountpoint -- the filesystem's mountpoint
-                label -- the filesystem label
-                uuid -- the filesystem UUID
-                mountopts -- mount options for the filesystem
-                size -- the filesystem's size in MiB
-                exists -- indicates whether this is an existing filesystem
+        """
+            :keyword device: path to the block device node (required for
+                             existing filesystems)
+            :keyword mountpoint: the filesystem's planned mountpoint
+            :keyword label: the filesystem label
+            :keyword uuid: the filesystem UUID
+            :keyword mountopts: mount options for the filesystem
+            :type mountopts: str
+            :keyword size: the filesystem's size in MiB
+            :keyword exists: indicates whether this is an existing filesystem
+            :type exists: bool
                 
+            .. note::
+
+                The 'device' kwarg is required for existing formats. For non-
+                existent formats, it is only necessary that the :attr:`device`
+                attribute be set before the :meth:`create` method runs. Note
+                that you can specify the device at the last moment by specifying
+                it via the 'device' kwarg to the :meth:`create` method.
         """
         if self.__class__ is FS:
             raise TypeError("FS is an abstract class.")
@@ -250,9 +257,10 @@ class FS(DeviceFormat):
         return buf
 
     def _getExistingSize(self, info=None):
-        """ Determine the size of this filesystem.  Filesystem must
-            exist.  Each filesystem varies, but the general procedure
-            is to run the filesystem dump or info utility and read
+        """ Determine the size of this filesystem.
+
+            Filesystem must exist.  Each filesystem varies, but the general
+            procedure is to run the filesystem dump or info utility and read
             the block size and number of blocks for the filesystem
             and compute megabytes from that.
 
@@ -281,6 +289,11 @@ class FS(DeviceFormat):
             are looking for, the command to run and arguments, or
             something else.  If you catch an exception from this method,
             assume the filesystem cannot be resized.
+
+            :keyword info: filesystem info buffer
+            :type info: str (output of :attr:`infofsProg`)
+            :returns: size of existing fs in MiB.
+            :rtype: float.
         """
         size = self._size
 
@@ -359,14 +372,9 @@ class FS(DeviceFormat):
     def doFormat(self, *args, **kwargs):
         """ Create the filesystem.
 
-            Arguments:
-
-                None
-
-            Keyword Arguments:
-
-                options -- list of options to pass to mkfs
-
+            :keyword options: options to pass to mkfs
+            :type options: list of strings
+            :raises: FormatCreateError, FSError
         """
         log_method_call(self, type=self.mountType, device=self.device,
                         mountpoint=self.mountpoint)
@@ -410,13 +418,10 @@ class FS(DeviceFormat):
         return argv
 
     def doResize(self, *args, **kwargs):
-        """ Resize this filesystem to new size @newsize.
+        """ Resize this filesystem based on this instance's targetSize attr.
 
-            Arguments:
-
-                None
+            :raises: FSResizeError, FSError
         """
-
         if not self.exists:
             raise FSResizeError("filesystem does not exist", self.device)
 
@@ -470,6 +475,10 @@ class FS(DeviceFormat):
         return _("Unknown return code: %d.") % (rc,)
 
     def doCheck(self):
+        """ Run a filesystem check.
+
+            :raises: FSError
+        """
         if not self.exists:
             raise FSError("filesystem has not been created")
 
@@ -511,7 +520,7 @@ class FS(DeviceFormat):
                 self._supported = False
                 return
 
-        # If we successfully loaded a kernel module, for this filesystem, we
+        # If we successfully loaded a kernel module for this filesystem, we
         # also need to update the list of supported filesystems.
         update_kernel_filesystems()
 
@@ -520,7 +529,7 @@ class FS(DeviceFormat):
         ret = False
 
         if self.status:
-            raise RuntimeError("filesystem is already mounted")
+            return True
 
         # create a temp dir
         prefix = "%s.%s" % (os.path.basename(self.device), self.type)
@@ -542,15 +551,11 @@ class FS(DeviceFormat):
     def mount(self, *args, **kwargs):
         """ Mount this filesystem.
 
-            Arguments:
-
-                None
-
-            Keyword Arguments:
-
-                options -- mount options (overrides all other option strings)
-                chroot -- prefix to apply to mountpoint
-                mountpoint -- mountpoint (overrides self.mountpoint)
+            :keyword options: mount options (overrides all other option strings)
+            :type options: str.
+            :keyword chroot: prefix to apply to mountpoint
+            :keyword mountpoint: mountpoint (overrides self.mountpoint)
+            :raises: FSError
         """
         options = kwargs.get("options", "")
         chroot = kwargs.get("chroot", "/")
@@ -636,7 +641,11 @@ class FS(DeviceFormat):
         return argv 
 
     def writeLabel(self, label):
-        """ Create a label for this filesystem. """
+        """ Create a label for this filesystem.
+
+            :param label: the label text
+            :raises: FSError
+        """
         if not self.exists:
             raise FSError("filesystem has not been created")
 
@@ -775,6 +784,18 @@ class FS(DeviceFormat):
     # generically named methods so filesystems and formatted devices
     # like swap and LVM physical volumes can have a common API.
     def create(self, *args, **kwargs):
+        """ Create the filesystem on the specified block device.
+
+            :keyword device: path to device node
+            :type device: str.
+            :raises: FormatCreateError, FSError
+            :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.
+        """
         if self.exists:
             raise FSError("filesystem already exists")
 
@@ -786,7 +807,19 @@ class FS(DeviceFormat):
         """ Mount the filesystem.
 
             The filesystem will be mounted at the directory indicated by
-            self.mountpoint.
+            self.mountpoint unless overridden via the 'mountpoint' kwarg.
+
+            :keyword device: device node path
+            :type device: str.
+            :keyword mountpoint: mountpoint (overrides self.mountpoint)
+            :type mountpoint: 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.
         """
         return self.mount(**kwargs)
 
@@ -882,7 +915,12 @@ class Ext2FS(FS):
             raise FSError("failed to set UUID for %s: %s" % (self.device, err))
 
     def _getMinSize(self, info=None):
-        """ Minimum size for this filesystem in MB. """
+        """ Set the minimum size for this filesystem in MiB.
+
+            :keyword info: filesystem info buffer
+            :type info: str (output of :attr:`infofsProg`)
+            :rtype: None.
+        """
         size = self._minSize
         blockSize = None
 
@@ -1055,6 +1093,23 @@ class BTRFS(FS):
         pass
 
     def setup(self, *args, **kwargs):
+        """ Mount the filesystem.
+
+            The filesystem will be mounted at the directory indicated by
+            self.mountpoint unless overridden via the 'mountpoint' kwarg.
+
+            :keyword device: device node path
+            :type device: str.
+            :keyword mountpoint: mountpoint (overrides self.mountpoint)
+            :type mountpoint: 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, type=self.mountType, device=self.device,
                         mountpoint=self.mountpoint)
         if not self.mountpoint and "mountpoint" not in kwargs:
@@ -1299,7 +1354,12 @@ class NTFS(FS):
         return False
 
     def _getMinSize(self, info=None):
-        # try to determine the minimum size.
+        """ Set the minimum size for this filesystem in MiB.
+
+            :keyword info: filesystem info buffer
+            :type info: str (output of :attr:`infofsProg`)
+            :rtype: None.
+        """
         size = self._minSize
         if self.exists and os.path.exists(self.device) and \
            util.find_program_in_path(self.resizefsProg):
diff --git a/blivet/formats/luks.py b/blivet/formats/luks.py
index 0c4b25b..011208e 100644
--- a/blivet/formats/luks.py
+++ b/blivet/formats/luks.py
@@ -43,7 +43,7 @@ log = logging.getLogger("blivet")
 
 
 class LUKS(DeviceFormat):
-    """ A LUKS device. """
+    """ LUKS """
     _type = "luks"
     _name = "LUKS"
     _lockedName = _("Encrypted")
@@ -54,20 +54,32 @@ class LUKS(DeviceFormat):
     _packages = ["cryptsetup-luks"]     # required packages
 
     def __init__(self, *args, **kwargs):
-        """ Create a LUKS instance.
-
-            Keyword Arguments:
-
-                device -- the path to the underlying device
-                name -- the name of the mapped device
-                uuid -- this device's UUID
-                passphrase -- device passphrase (string)
-                key_file -- path to a file containing a key (string)
-                cipher -- cipher mode string
-                key_size -- key size in bits
-                exists -- indicates whether this is an existing format
-                escrow_cert -- certificate to use for key escrow
-                add_backup_passphrase -- generate a backup passphrase?
+        """
+            :keyword device: the path to the underlying device
+            :keyword uuid: the LUKS UUID
+            :keyword exists: indicates whether this is an existing format
+            :type exists: bool
+            :keyword name: the name of the mapped device
+            :keyword passphrase: device passphrase
+            :type passphrase: str
+            :keyword key_file: path to a file containing a key
+            :type key_file: str
+            :keyword cipher: cipher mode
+            :type cipher: str
+            :keyword key_size: key size in bits
+            :type key_size: int
+            :keyword escrow_cert: certificate (contents) to use for key escrow
+            :type escrow_cert: str
+            :keyword add_backup_passphrase: generate a backup passphrase?
+            :type add_backup_passphrase: bool.
+
+            .. note::
+
+                The 'device' kwarg is required for existing formats. For non-
+                existent formats, it is only necessary that the :attr:`device`
+                attribute be set before the :meth:`create` method runs. Note
+                that you can specify the device at the last moment by specifying
+                it via the 'device' kwarg to the :meth:`create` method.
         """
         log_method_call(self, *args, **kwargs)
         DeviceFormat.__init__(self, *args, **kwargs)
@@ -157,7 +169,18 @@ class LUKS(DeviceFormat):
         raise NotImplementedError("probe method not defined for LUKS")
 
     def setup(self, *args, **kwargs):
-        """ Open, or set up, the format. """
+        """ Open the encrypted block device.
+
+            :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, mapName=self.mapName,
                         type=self.type, status=self.status)
         if not self.configured:
@@ -183,7 +206,18 @@ class LUKS(DeviceFormat):
             crypto.luks_close(self.mapName)
 
     def create(self, *args, **kwargs):
-        """ Create the format. """
+        """ 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)
         if not self.hasKey:
@@ -207,7 +241,11 @@ class LUKS(DeviceFormat):
             self.notifyKernel()
 
     def destroy(self, *args, **kwargs):
-        """ Create the format. """
+        """ 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)
         self.teardown()
diff --git a/blivet/formats/lvmpv.py b/blivet/formats/lvmpv.py
index 4111ad0..5c1f8f5 100644
--- a/blivet/formats/lvmpv.py
+++ b/blivet/formats/lvmpv.py
@@ -49,17 +49,23 @@ class LVMPhysicalVolume(DeviceFormat):
     _ksMountpoint = "pv."
 
     def __init__(self, *args, **kwargs):
-        """ Create an LVMPhysicalVolume instance.
-
-            Keyword Arguments:
-
-                device -- path to the underlying device
-                uuid -- this PV's uuid (not the VG uuid)
-                vgName -- the name of the VG this PV belongs to
-                vgUuid -- the UUID of the VG this PV belongs to
-                peStart -- offset of first physical extent
-                exists -- indicates whether this is an existing format
-
+        """
+            :keyword device: path to the block device node
+            :keyword uuid: this PV's uuid (not the VG uuid)
+            :keyword exists: indicates whether this is an existing format
+            :type exists: bool
+            :keyword vgName: the name of the VG this PV belongs to
+            :keyword vgUuid: the UUID of the VG this PV belongs to
+            :keyword peStart: offset of first physical extent
+            :type peStart: float
+
+            .. note::
+
+                The 'device' kwarg is required for existing formats. For non-
+                existent formats, it is only necessary that the :attr:`device`
+                attribute be set before the :meth:`create` method runs. Note
+                that you can specify the device at the last moment by specifying
+                it via the 'device' kwarg to the :meth:`create` method.
         """
         log_method_call(self, *args, **kwargs)
         DeviceFormat.__init__(self, *args, **kwargs)
@@ -98,7 +104,18 @@ class LVMPhysicalVolume(DeviceFormat):
         #self.vgUuid = info['vg_uuid']
 
     def create(self, *args, **kwargs):
-        """ Create the format. """
+        """ 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)
 
@@ -121,7 +138,11 @@ class LVMPhysicalVolume(DeviceFormat):
         self.notifyKernel()
 
     def destroy(self, *args, **kwargs):
-        """ Destroy the format. """
+        """ 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)
         if not self.exists:
diff --git a/blivet/formats/mdraid.py b/blivet/formats/mdraid.py
index 44d111e..8a73840 100644
--- a/blivet/formats/mdraid.py
+++ b/blivet/formats/mdraid.py
@@ -49,15 +49,16 @@ class MDRaidMember(DeviceFormat):
     _ksMountpoint = "raid."
     
     def __init__(self, *args, **kwargs):
-        """ Create a MDRaidMember instance.
-
-            Keyword Arguments:
+        """
+            :keyword device: path to block device node
+            :keyword uuid: this member device's uuid
+            :keyword exists: whether this is an existing format
+            :type exists: bool
+            :keyword mdUuid: the uuid of the array this device belongs to
 
-                device -- path to underlying device
-                uuid -- this member device's uuid
-                mdUuid -- the uuid of the array this device belongs to
-                exists -- indicates whether this is an existing format
+            .. note::
 
+                The 'device' kwarg is required for existing formats.
         """
         log_method_call(self, *args, **kwargs)
         DeviceFormat.__init__(self, *args, **kwargs)
@@ -93,6 +94,11 @@ class MDRaidMember(DeviceFormat):
             self.raidMinor = info['mdMinor']
 
     def destroy(self, *args, **kwargs):
+        """ Remove the formatting from the associated block device.
+
+            :raises: FormatDestroyError
+            :returns: None.
+        """
         if not self.exists:
             raise MDMemberError("format does not exist")
 
diff --git a/blivet/formats/multipath.py b/blivet/formats/multipath.py
index 4102cb0..893c446 100644
--- a/blivet/formats/multipath.py
+++ b/blivet/formats/multipath.py
@@ -49,16 +49,11 @@ class MultipathMember(DeviceFormat):
     _hidden = True                      # hide devices with this formatting?
 
     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
-
-            On initialization this format is like DeviceFormat
-
+        """
+            :keyword device: path to the underlying device (required)
+            :keyword uuid: this format's UUID
+            :keyword exists: whether this is an existing format
+            :type exists: bool
         """
         log_method_call(self, *args, **kwargs)
         DeviceFormat.__init__(self, *args, **kwargs)
diff --git a/blivet/formats/prepboot.py b/blivet/formats/prepboot.py
index c7ed111..3939af5 100644
--- a/blivet/formats/prepboot.py
+++ b/blivet/formats/prepboot.py
@@ -40,19 +40,36 @@ class PPCPRePBoot(DeviceFormat):
     _minSize = 4                        # minimum size in MB
 
     def __init__(self, *args, **kwargs):
-        """ Create a PRePBoot instance.
-
-            Keyword Arguments:
+        """
+            :keyword device: path to block device node
+            :keyword exists: whether this is an existing format
+            :type exists: bool
 
-                device -- path to the underlying device
-                exists -- indicates whether this is an existing format
+            .. note::
 
+                The 'device' kwarg is required for existing formats. For non-
+                existent formats, it is only necessary that the :attr:`device`
+                attribute be set before the :meth:`create` method runs. Note
+                that you can specify the device at the last moment by specifying
+                it via the 'device' kwarg to the :meth:`create` method.
         """
         DeviceFormat.__init__(self, *args, **kwargs)
 
     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.
+        """
         if self.exists:
-            raise FSError("PReP Boot format already exists")
+            raise FormatCreateError("PReP Boot format already exists")
 
         DeviceFormat.create(self, *args, **kwargs)
 
diff --git a/blivet/formats/swap.py b/blivet/formats/swap.py
index da8f4df..051963b 100644
--- a/blivet/formats/swap.py
+++ b/blivet/formats/swap.py
@@ -49,16 +49,22 @@ class SwapSpace(DeviceFormat):
     _maxSize = 128 * 1024
 
     def __init__(self, *args, **kwargs):
-        """ Create a SwapSpace instance.
-
-            Keyword Arguments:
-
-                device -- path to the underlying device
-                uuid -- this swap space's uuid
-                label -- this swap space's label
-                priority -- this swap space's priority
-                exists -- indicates whether this is an existing format
-
+        """
+            :keyword device: path to the block device node
+            :keyword uuid: this swap space's uuid
+            :keyword exists: whether this is an existing format
+            :type exists: bool
+            :keyword label: this swap space's label
+            :keyword priority: this swap space's priority
+            :type priority: int
+
+            .. note::
+
+                The 'device' kwarg is required for existing formats. For non-
+                existent formats, it is only necessary that the 'device'
+                attribute be set before the :meth:`~.SwapSpace.create` method
+                runs. You can specify the device at the last moment by via the
+                'device' kwarg to the :meth:`~.SwapSpace.create` method.
         """
         log_method_call(self, *args, **kwargs)
         DeviceFormat.__init__(self, *args, **kwargs)
@@ -123,7 +129,18 @@ class SwapSpace(DeviceFormat):
         return self.exists and swap.swapstatus(self.device)
 
     def setup(self, *args, **kwargs):
-        """ Open, or set up, a device. """
+        """ 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)
         if not self.exists:
@@ -146,18 +163,23 @@ class SwapSpace(DeviceFormat):
             swap.swapoff(self.device)
 
     def create(self, *args, **kwargs):
-        """ Create the device. """
+        """ 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)
-        force = kwargs.get("force")
-        if not force and self.exists:
+        if self.exists:
             raise SwapSpaceError("format already exists")
 
-        if force:
-            self.teardown()
-        elif self.status:
-            raise SwapSpaceError("device exists and is active")
-
         try:
             DeviceFormat.create(self, *args, **kwargs)
             swap.mkswap(self.device, label=self.label)
diff --git a/blivet/iscsi.py b/blivet/iscsi.py
index fceb881..4c9d7e8 100644
--- a/blivet/iscsi.py
+++ b/blivet/iscsi.py
@@ -407,7 +407,4 @@ class iscsi(object):
 
         return nodeDisks
 
-# Create iscsi singleton
-iscsi = iscsi()
-
 # vim:tw=78:ts=4:et:sw=4
-- 
1.8.1.4

