Added docstrings to the Volume class

doapi/doapi.py

@@ -281,8 +281,8 @@ def create_droplet(self, name, image, size, region, ssh_keys=None,
             for the new droplet
         :param str user_data: a string of user data/metadata for the droplet
         :param volumes: an iterable of volumes to attach to the new droplet,
-            specified as either IDs or `Volume` objects
-        :type volumes: iterable of strings and/or `Volume`s
+            specified as volume IDs and/or `Volume` objects
+        :type volumes: iterable
         :param kwargs: additional fields to include in the API request
         :return: the new droplet resource
         :rtype: Droplet

doapi/volume.py

@@ -2,7 +2,39 @@
 from   .base import Actionable, Region, fromISO8601
 
 class Volume(Actionable):
-    """ TODO """
+    """
+    .. versionadded:: 0.3.0
+
+    A block storage volume resource, representing data storage that can be
+    added to a droplet and moved between droplets in the same region.
+
+    New volumes are created via the :meth:`doapi.create_volume` method and can
+    be retrieved with the :meth:`doapi.fetch_volume` and
+    :meth:`doapi.fetch_all_volumes` methods.
+
+    The DigitalOcean API specifies the following fields for volume objects:
+
+    :var id: a unique identifier for the volume
+    :vartype id: string
+
+    :var created_at: date & time of the volume's creation
+    :vartype created_at: datetime.datetime
+
+    :var description: a human-readable description for the volume
+    :vartype description: string
+
+    :var droplet_ids: IDs of droplets that the volume is currently attached to
+    :vartype droplet_ids: list of integers
+
+    :var name: a human-readable name for the volume
+    :vartype name: string
+
+    :var region: the region in which the volume is located
+    :vartype region: `Region`
+
+    :var size_gigabytes: the size of the volume in gigabytes
+    :vartype size_gigabytes: integer
+    """
 
     def __init__(self, state=None, **extra):
         if isinstance(state, string_types):
@@ -14,7 +46,7 @@ def __init__(self, state=None, **extra):
         self.created_at = fromISO8601(self.get('created_at'))
 
     def __str__(self):
-        """ TODO """
+        """ Convert the volume object to its ID """
         return self.id
 
     @property
@@ -44,13 +76,40 @@ def delete(self):
         self.doapi_manager.request(self.url, method='DELETE')
 
     def attach(self, droplet_id):
-        """ TODO """
+        """
+        Attach the volume to a droplet
+
+        :param droplet_id: the droplet to attach the volume to
+        :type droplet_id: integer or `Droplet`
+        :return: an `Action` representing the in-progress operation on the
+            volume
+        :rtype: Action
+        :raises DOAPIError: if the API endpoint replies with an error
+        """
         return self.act(type='attach', droplet_id=int(droplet_id))
 
     def detach(self, droplet_id):
-        """ TODO """
+        """
+        Detach the volume from a droplet
+
+        :param droplet_id: the droplet from which to remove the volume
+        :type droplet_id: integer or `Droplet`
+        :return: an `Action` representing the in-progress operation on the
+            volume
+        :rtype: Action
+        :raises DOAPIError: if the API endpoint replies with an error
+        """
         return self.act(type='detach', droplet_id=int(droplet_id))
 
     def resize(self, size_gigabytes):
-        """ TODO """
+        """
+        Resize the volume
+
+        :param size_gigabytes: the new size of the volume in gigabytes
+        :type size_gigabytes: integer
+        :return: an `Action` representing the in-progress operation on the
+            volume
+        :rtype: Action
+        :raises DOAPIError: if the API endpoint replies with an error
+        """
         return self.act(type='resize', size_gigabytes=size_gigabytes)