Driver documentation cleanup

Adding more details to volume driver interface documenation.

Change-Id: I79117625aa3b2d7adf57ddab7e5889bebb450176

cinder/interface/volume_driver.py

@@ -78,9 +78,18 @@ class VolumeDriverCore(base.CinderInterface):
             string such as: "iSCSI", "FC", "nfs", "ceph", etc.
         * total_capacity_gb
             The total capacity in gigabytes (GiB) of the storage backend being
-            used to store Cinder volumes.
+            used to store Cinder volumes. Use keyword 'unknown' if the backend
+            cannot report the value or 'infinite' if there is no upper limit.
+            But, it is recommended to report real values as the Cinder
+            scheduler assigns lowest weight to any storage backend reporting
+            'unknown' or 'infinite'.
+
         * free_capacity_gb
-            The free capacity in gigabytes (GiB).
+            The free capacity in gigabytes (GiB). Use keyword 'unknown' if the
+            backend cannot report the value or 'infinite' if there is no upper
+            limit. But, it is recommended to report real values as the Cinder
+            scheduler assigns lowest weight to any storage backend reporting
+            'unknown' or 'infinite'.
 
         And the following optional fields:
 

cinder/interface/volume_management_driver.py

@@ -53,8 +53,15 @@ class VolumeManagementDriver(base.CinderInterface):
         ManageExistingVolumeTypeMismatch, specifying a reason for the failure.
 
         :param volume:       Cinder volume to manage
-        :param existing_ref: Driver-specific information used to identify a
-                             volume
+        :param existing_ref: Dictionary with keys 'source-id', 'source-name'
+                             with driver-specific values to identify a backend
+                             storage object.
+        :raises: ManageExistingInvalidReference If the existing_ref doesn't
+                 make sense, or doesn't refer to an existing backend storage
+                 object.
+        :raises: ManageExistingVolumeTypeMismatch If there is a mismatch
+                 between the volume type and the properties of the existing
+                 backend storage object.
         """
 
     def manage_existing_get_size(self, volume, existing_ref):
@@ -63,8 +70,12 @@ class VolumeManagementDriver(base.CinderInterface):
         When calculating the size, round up to the next GB.
 
         :param volume:       Cinder volume to manage
-        :param existing_ref: Driver-specific information used to identify a
-                             volume
+        :param existing_ref: Dictionary with keys 'source-id', 'source-name'
+                             with driver-specific values to identify a backend
+                             storage object.
+        :raises: ManageExistingInvalidReference If the existing_ref doesn't
+                 make sense, or doesn't refer to an existing backend storage
+                 object.
         """
 
     def unmanage(self, volume):

cinder/interface/volume_snapshotmanagement_driver.py

@@ -44,7 +44,9 @@ class VolumeSnapshotManagementDriver(base.CinderInterface):
            backend storage object when required.
 
         :param snapshot: The snapshot to manage.
-        :param existing_ref: A reference to the existing snap.
+        :param existing_ref: Dictionary with keys 'source-id', 'source-name'
+                             with driver-specific values to identify a backend
+                             storage object.
         :raises: ManageExistingInvalidReference If the existing_ref doesn't
                  make sense, or doesn't refer to an existing backend storage
                  object.
@@ -55,8 +57,13 @@ class VolumeSnapshotManagementDriver(base.CinderInterface):
 
         When calculating the size, round up to the next GB.
 
-        :param snapshot: The snapshot.
-        :param existing_ref: A reference to the existing snap.
+        :param snapshot: The snapshot to manage.
+        :param existing_ref: Dictionary with keys 'source-id', 'source-name'
+                             with driver-specific values to identify a backend
+                             storage object.
+        :raises: ManageExistingInvalidReference If the existing_ref doesn't
+                 make sense, or doesn't refer to an existing backend storage
+                 object.
         """
 
     def unmanage_snapshot(self, snapshot):

doc/source/devref/drivers.rst

@@ -28,9 +28,10 @@ There are some basic attributes that all drivers classes should have:
 
 * VERSION: Driver version in string format.  No naming convention is imposed,
   although semantic versioning is recommended.
-* CI_WIKI_NAME: Must be the exact name of the ThirdPartySystems wiki page.
-  This is used by our tooling system to associated jobs to drivers and
-  track their CI reporting status correctly.
+* CI_WIKI_NAME: Must be the exact name of the `ThirdPartySystems wiki page
+  <https://wiki.openstack.org/wiki/ThirdPartySystems>`_. This is used by our
+  tooling system to associate jobs to drivers and track their CI reporting
+  status correctly.
 
 The tooling system will also use the name and docstring of the driver class.
 
@@ -63,7 +64,6 @@ provided by a driver.
 
 * driver_version
 * free_capacity_gb
-* reserved_percentage
 * storage_protocol
 * total_capacity_gb
 * vendor_name
@@ -71,8 +71,9 @@ provided by a driver.
 
 **NOTE:** If the driver is unable to provide a value for free_capacity_gb or
 total_capacity_gb, keywords can be provided instead. Please use 'unknown' if
-the array cannot report the value or 'infinite' if the array has no upper
-limit.
+the backend cannot report the value or 'infinite' if the backend has no upper
+limit. But, it is recommended to report real values as the Cinder scheduler
+assigns lowest weight to any storage backend reporting 'unknown' or 'infinite'.
 
 Feature Enforcement
 -------------------