Improve docs for v3 endpoints

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

Change-Id: I543e5475417ee1f333733f3a159c64223e44f1f2
Partial-Bug: #1330769

keystoneclient/v3/endpoints.py

@@ -33,7 +33,8 @@ class Endpoint(base.Resource):
         * region: geographic location of the endpoint
         * service_id: service to which the endpoint belongs
         * url: fully qualified service endpoint
-        * enabled: determines whether the endpoint appears in the catalog
+        * enabled: determines whether the endpoint appears in the service
+                   catalog
 
     """
 
@@ -56,6 +57,24 @@ class EndpointManager(base.CrudManager):
     @positional(1, enforcement=positional.WARN)
     def create(self, service, url, interface=None, region=None, enabled=True,
                **kwargs):
+        """Create an endpoint.
+
+        :param service: the service to which the endpoint belongs.
+        :type service: str or :class:`keystoneclient.v3.services.Service`
+        :param str url: the URL of the fully qualified service endpoint.
+        :param str interface: the network interface of the endpoint. Valid
+                             values are: ``public``, ``admin`` or ``internal``.
+        :param region: the region to which the endpoint belongs.
+        :type region: str or :class:`keystoneclient.v3.regions.Region`
+        :param bool enabled: whether the endpoint is enabled or not,
+                             determining if it appears in the service catalog.
+        :param kwargs: any other attribute provided will be passed to the
+                       server.
+
+        :returns: the created endpoint returned from server.
+        :rtype: :class:`keystoneclient.v3.endpoints.Endpoint`
+
+        """
         self._validate_interface(interface)
         return super(EndpointManager, self).create(
             service_id=base.getid(service),
@@ -66,6 +85,15 @@ class EndpointManager(base.CrudManager):
             **kwargs)
 
     def get(self, endpoint):
+        """Retrieve an endpoint.
+
+        :param endpoint: the endpoint to be retrieved from the server.
+        :type endpoint: str or :class:`keystoneclient.v3.endpoints.Endpoint`
+
+        :returns: the specified endpoint returned from server.
+        :rtype: :class:`keystoneclient.v3.endpoints.Endpoint`
+
+        """
         return super(EndpointManager, self).get(
             endpoint_id=base.getid(endpoint))
 
@@ -74,8 +102,20 @@ class EndpointManager(base.CrudManager):
              region_id=None, **kwargs):
         """List endpoints.
 
-        If ``**kwargs`` are provided, then filter endpoints with
-        attributes matching ``**kwargs``.
+        :param service: the service of the endpoints to be filtered on.
+        :type service: str or :class:`keystoneclient.v3.services.Service`
+        :param str interface: the network interface of the endpoints to be
+                              filtered on. Valid values are: ``public``,
+                              ``admin`` or ``internal``.
+        :param bool enabled: whether to return enabled or disabled endpoints.
+        :param str region_id: filter endpoints by the region_id attribute. If
+                              both region and region_id are specified, region
+                              takes precedence.
+        :param kwargs: any other attribute provided will filter endpoints on.
+
+        :returns: a list of endpoints.
+        :rtype: list of :class:`keystoneclient.v3.endpoints.Endpoint`
+
         """
         # NOTE(lhcheng): region filter is not supported by keystone,
         # region_id should be used instead. Consider removing the
@@ -91,6 +131,26 @@ class EndpointManager(base.CrudManager):
     @positional(enforcement=positional.WARN)
     def update(self, endpoint, service=None, url=None, interface=None,
                region=None, enabled=None, **kwargs):
+        """Update an endpoint.
+
+        :param endpoint: the endpoint to be updated on the server.
+        :type endpoint: str or :class:`keystoneclient.v3.endpoints.Endpoint`
+        :param service: the new service to which the endpoint belongs.
+        :type service: str or :class:`keystoneclient.v3.services.Service`
+        :param str url: the new URL of the fully qualified service endpoint.
+        :param str interface: the new network interface of the endpoint. Valid
+                             values are: ``public``, ``admin`` or ``internal``.
+        :param region: the new region to which the endpoint belongs.
+        :type region: str or :class:`keystoneclient.v3.regions.Region`
+        :param bool enabled: determining if the endpoint appears in the service
+                             catalog by enabling or disabling it.
+        :param kwargs: any other attribute provided will be passed to the
+                       server.
+
+        :returns: the updated endpoint returned from server.
+        :rtype: :class:`keystoneclient.v3.endpoints.Endpoint`
+
+        """
         self._validate_interface(interface)
         return super(EndpointManager, self).update(
             endpoint_id=base.getid(endpoint),
@@ -102,5 +162,14 @@ class EndpointManager(base.CrudManager):
             **kwargs)
 
     def delete(self, endpoint):
+        """Delete an endpoint.
+
+        :param endpoint: the endpoint to be deleted on the server.
+        :type endpoint: str or :class:`keystoneclient.v3.endpoints.Endpoint`
+
+        :returns: Response object with 204 status.
+        :rtype: :class:`requests.models.Response`
+
+        """
         return super(EndpointManager, self).delete(
             endpoint_id=base.getid(endpoint))