Need to have stable implementation of nova_volume_detach()
and add missing docstrings

Earlier implementation of this api just detached the
volume and wait for the volume to be in 'available'
state.
But the scenario manager don't really verify the state
of the volume. Tempest plugins do verify the state.

Implements: blueprint tempest-scenario-manager-stable
Signed-off by: Soniya Vyas<svyas@redhat.com>
Change-Id: I023177c09cf035bbb29941cc5d4bb4cc6c60ed1c
diff --git a/tempest/scenario/manager.py b/tempest/scenario/manager.py
index add4c37..ff860d5 100644
--- a/tempest/scenario/manager.py
+++ b/tempest/scenario/manager.py
@@ -698,21 +698,30 @@
         return snapshot_image
 
     def nova_volume_attach(self, server, volume_to_attach):
-        """Attach nova volume"""
+        """Compute volume attach
+
+        This utility attaches volume from compute and waits for the
+        volume status to be 'in-use' state.
+        """
         volume = self.servers_client.attach_volume(
             server['id'], volumeId=volume_to_attach['id'])['volumeAttachment']
         self.assertEqual(volume_to_attach['id'], volume['id'])
         waiters.wait_for_volume_resource_status(self.volumes_client,
                                                 volume['id'], 'in-use')
-
         # Return the updated volume after the attachment
         return self.volumes_client.show_volume(volume['id'])['volume']
 
     def nova_volume_detach(self, server, volume):
-        """Detach nova volume"""
+        """Compute volume detach
+
+        This utility detaches volume from compute and check whether the
+        volume status is 'available' state, and if not, an exception
+        will be thrown.
+        """
         self.servers_client.detach_volume(server['id'], volume['id'])
         waiters.wait_for_volume_resource_status(self.volumes_client,
                                                 volume['id'], 'available')
+        volume = self.volumes_client.show_volume(volume['id'])['volume']
 
     def ping_ip_address(self, ip_address, should_succeed=True,
                         ping_timeout=None, mtu=None, server=None):