Merge "Improve docs for v3 endpoints"

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))