Improve docs for v3 regions

In preparation to add functional tests for v3 regions, this
change proposes to detail the method docs, because the tests
need to be based on them.

Change-Id: I8d2169608d4acdc95116f49ea45cb6a15ba3b6e3
Partial-Bug: #1330769

keystoneclient/v3/regions.py

@@ -18,12 +18,10 @@ class Region(base.Resource):
 
     Attributes:
         * id: a string that identifies the region.
-        * description: a string that describes the region. Optional.
+        * description: a string that describes the region.
-        * parent_region_id: string that is the id field for a pre-existing
+        * parent_region_id: a pre-existing region in the backend or its ID
-                            region in the backend. Allows for hierarchical
+                            field. Allows for hierarchical region organization.
-                            region organization.
         * enabled: determines whether the endpoint appears in the catalog.
-        Defaults to True
     """
 
     pass
@@ -38,15 +36,20 @@ class RegionManager(base.CrudManager):
 
     def create(self, id=None, description=None, enabled=True,
                parent_region=None, **kwargs):
-        """Create a Catalog region.
+        """Create a region.
 
-        :param id: a string that identifies the region. If not specified a
+        :param str id: the unique identifier of the region. If not specified an
-                   unique identifier will be assigned to the region.
+                       ID will be created by the server.
-        :param description: a string that describes the region.
+        :param str description: the description of the region.
-        :param parent_region: string that is the id field for a pre-existing
+        :param bool enabled: whether the region is enabled or not, determining
-                              region in the backend. Allows for hierarchical
+                             if it appears in the catalog.
-                              region organization.
+        :param parent_region: the parent of the region in the hierarchy.
-        :param enabled: determines whether the endpoint appears in the catalog.
+        :type parent_region: str or :class:`keystoneclient.v3.regions.Region`
+        :param kwargs: any other attribute provided will be passed to the
+                       server.
+
+        :returns: the created region returned from server.
+        :rtype: :class:`keystoneclient.v3.regions.Region`
 
         """
         return super(RegionManager, self).create(
@@ -54,28 +57,45 @@ class RegionManager(base.CrudManager):
             parent_region_id=base.getid(parent_region), **kwargs)
 
     def get(self, region):
+        """Retrieve a region.
+
+        :param region: the region to be retrieved from the server.
+        :type region: str or :class:`keystoneclient.v3.regions.Region`
+
+        :returns: the specified region returned from server.
+        :rtype: :class:`keystoneclient.v3.regions.Region`
+
+        """
         return super(RegionManager, self).get(
             region_id=base.getid(region))
 
     def list(self, **kwargs):
         """List regions.
 
-        If ``**kwargs`` are provided, then filter regions with
+        :param kwargs: any attributes provided will filter regions on.
-        attributes matching ``**kwargs``.
+
+        :returns: a list of regions.
+        :rtype: list of :class:`keystoneclient.v3.regions.Region`.
+
         """
         return super(RegionManager, self).list(
             **kwargs)
 
     def update(self, region, description=None, enabled=None,
                parent_region=None, **kwargs):
-        """Update a Catalog region.
+        """Update a region.
 
-        :param region: a string that identifies the region.
+        :param region: the region to be updated on the server.
-        :param description: a string that describes the region.
+        :type region: str or :class:`keystoneclient.v3.regions.Region`
-        :param parent_region: string that is the id field for a pre-existing
+        :param str description: the new description of the region.
-                              region in the backend.  Allows for hierarchical
+        :param bool enabled: determining if the region appears in the catalog
-                              region organization.
+                             by enabling or disabling it.
-        :param enabled: determines whether the endpoint appears in the catalog.
+        :param parent_region: the new parent of the region in the hierarchy.
+        :type parent_region: str or :class:`keystoneclient.v3.regions.Region`
+        :param kwargs: any other attribute provided will be passed to server.
+
+        :returns: the updated region returned from server.
+        :rtype: :class:`keystoneclient.v3.regions.Region`
 
         """
         return super(RegionManager, self).update(
@@ -86,5 +106,14 @@ class RegionManager(base.CrudManager):
             **kwargs)
 
     def delete(self, region):
+        """Delete a region.
+
+        :param region: the region to be deleted on the server.
+        :type region: str or :class:`keystoneclient.v3.regions.Region`
+
+        :returns: Response object with 204 status.
+        :rtype: :class:`requests.models.Response`
+
+        """
         return super(RegionManager, self).delete(
             region_id=base.getid(region))