api-ref: expand on various bdm parameters

Some of the block_device_mapping_v2 parameter descriptions
were lacking details on valid values, combinations, restrictions
and how things get linked together, for example, to get a swap
bdm. This fills in the details and re-words things in some
places for clarity.

The mention of the libvirt driver in the guest_format for
non-swap ephemeral block devices is removed since (1) it's
overly confusing and (2) API users shouldn't know or care
if the hypervisor running their server is libvirt or not.
The point is, if you want swap, ask for swap, and if you want
ephemeral, specify one of the other values. Then you get what
you get and you don't throw a fit.

Change-Id: Ia7e49f28e2f410ada5c2f4c2e3a13ffd97e54654

api-ref/source/parameters.yaml

@@ -1791,10 +1791,13 @@ block_device_mapping_v2:
   type: array
 block_device_uuid:
   description: |
-    This is the uuid of source resource. The uuid is point to different resource
-    based on the source_type. For example, if source_type is ``image`` as the above
-    sample, the block device is created based on the specified image which is gotten
-    from the image service.
+    This is the uuid of source resource. The uuid points to different resources
+    based on the ``source_type``. For example, if ``source_type`` is ``image``,
+    the block device is created based on the specified image which is retrieved
+    from the image service. Similarly, if ``source_type`` is ``snapshot`` then
+    the uuid refers to a volume snapshot in the block storage service. If
+    ``source_type`` is ``volume`` then the uuid refers to a volume in the block
+    storage service.
   in: body
   required: false
   type: string
@@ -2120,7 +2123,11 @@ description:
   type: string
 destination_type:
   description: |
-    Defines where the volume comes from. A valid value is ``local`` or ``volume``.
+    Defines where the block device mapping will reside. Valid values are:
+
+    * ``local``: The ephemeral disk resides local to the compute host on
+      which the server runs
+    * ``volume``: The persistent volume is stored in the block storage service
   in: body
   required: false
   type: string
@@ -3124,8 +3131,15 @@ group_id:
 guest_format:
   description: |
     Specifies the guest server disk file system format, such as ``ext2``,
-    ``ext3``, ``ext4``, ``xfs`` or ``swap``. This parameter affects only
-    the libvirt virt driver.
+    ``ext3``, ``ext4``, ``xfs`` or ``swap``.
+
+    Swap block device mappings have the following restrictions:
+
+    * The ``source_type`` must be ``blank``
+    * The ``destination_type`` must be ``local``
+    * There can only be one swap disk per server
+    * The size of the swap disk must be less than or equal to the ``swap``
+      size of the flavor
   in: body
   required: false
   type: string
@@ -5930,9 +5944,26 @@ snapshots:
   type: array
 source_type:
   description: |
-    The source type of the volume. A valid value is ``blank``, ``snapshot``,
-    ``volume``, or ``image``. If ``no_device`` is not specified,
-    this parameter is required.
+    The source type of the block device. Valid values are:
+
+    * ``blank``: Depending on the ``destination_type`` and ``guest_format``,
+      this will either be a blank persistent volume or an ephemeral (or swap)
+      disk local to the compute host on which the server resides
+    * ``image``: This is only valid with ``destination_type=volume``; creates
+      an image-backed volume in the block storage service and attaches it to
+      the server
+    * ``snapshot``: This is only valid with ``destination_type=volume``;
+      creates a volume backed by the given volume snapshot referenced via the
+      ``block_device_mapping_v2.uuid`` parameter and attaches it to the server
+    * ``volume``: This is only valid with ``destination_type=volume``; uses
+      the existing persistent volume referenced via the
+      ``block_device_mapping_v2.uuid`` parameter and attaches it to the server
+
+    This parameter is required unless ``block_device_mapping_v2.no_device`` is
+    specified.
+
+    See `Block Device Mapping in Nova <https://docs.openstack.org/nova/latest/user/block-device-mapping.html>`_
+    for more details on valid source and destination types.
   in: body
   required: false
   type: string