docs: add docstrings for Flask resource classes #268

- Also updated the existing ones for DataGateway API
ral-facilities · Jan 13, 2022 · a5aee61 · a5aee61
1 parent 71a0852
commit a5aee61
Show file tree

Hide file tree

Showing 2 changed files with 48 additions and 17 deletions.
diff --git a/datagateway_api/src/resources/entities/entity_endpoint.py b/datagateway_api/src/resources/entities/entity_endpoint.py
@@ -9,9 +9,9 @@
 
 def get_endpoint(name, entity_type, backend, **kwargs):
     """
-    Given an entity name generate a flask_restful Resource class.
-    In main.py these generated classes are registered with the api e.g
-    api.add_resource(get_endpoint("Datafiles", DATAFILE), "/datafiles")
+    Given an entity name, generate a flask_restful `Resource` class. In
+    `create_api_endpoints()`, these generated classes are registered with the API e.g.
+    `api.add_resource(get_endpoint("Datafiles", DATAFILE), "/datafiles")
 
     :param name: The name of the entity
     :type name: :class:`str`
@@ -168,9 +168,9 @@ def patch(self):
 
 def get_id_endpoint(name, entity_type, backend, **kwargs):
     """
-    Given an entity name generate a flask_restful Resource class.
-    In main.py these generated classes are registered with the api e.g
-    api.add_resource(get_endpoint("Datafiles", DATAFILE), "/datafiles/<int:id_>")
+    Given an entity name, generate a flask_restful `Resource` class. In
+    `create_api_endpoints()`, these generated classes are registered with the API e.g.
+    `api.add_resource(get_endpoint("Datafiles", DATAFILE), "/datafiles/<int:id_>")`
 
     :param name: The name of the entity
     :type name: :class:`str`
@@ -306,9 +306,9 @@ def patch(self, id_):
 
 def get_count_endpoint(name, entity_type, backend, **kwargs):
     """
-    Given an entity name generate a flask_restful Resource class.
-    In main.py these generated classes are registered with the api e.g
-    api.add_resource(get_endpoint("Datafiles", DATAFILE), "/datafiles/count")
+    Given an entity name, generate a flask_restful `Resource` class. In
+    `create_api_endpoints()`, these generated classes are registered with the API e.g.
+    `api.add_resource(get_endpoint("Datafiles", DATAFILE), "/datafiles/count")`
 
     :param name: The name of the entity
     :type name: :class:`str`
@@ -363,9 +363,9 @@ def get(self):
 
 def get_find_one_endpoint(name, entity_type, backend, **kwargs):
     """
-    Given an entity name generate a flask_restful Resource class.
-    In main.py these generated classes are registered with the api e.g
-    api.add_resource(get_endpoint("Datafiles", DATAFILE), "/datafiles/findone")
+    Given an entity name, generate a flask_restful `Resource` class. In
+    `create_api_endpoints()`, these generated classes are registered with the API e.g.
+    `api.add_resource(get_endpoint("Datafiles", DATAFILE), "/datafiles/findone")`
 
     :param name: The name of the entity
     :type name: :class:`str`

diff --git a/datagateway_api/src/resources/search_api_endpoints.py b/datagateway_api/src/resources/search_api_endpoints.py
@@ -16,7 +16,13 @@
 
 def get_search_endpoint(entity_name):
     """
-    TODO - Add docstring
+    Given an entity name, generate a flask_restful `Resource` class. In
+    `create_api_endpoints()`, these generated classes are registered with the API e.g.
+    `api.add_resource(get_search_endpoint("Dataset"), "/datasets")`
+
+    :param entity_name: Name of the entity
+    :type entity_name: :class:`str`
+    :return: Generated endpoint class
     """
 
     class Endpoint(Resource):
@@ -33,7 +39,13 @@ def get(self):
 
 def get_single_endpoint(entity_name):
     """
-    TODO - Add docstring
+    Given an entity name, generate a flask_restful `Resource` class. In
+    `create_api_endpoints()`, these generated classes are registered with the API e.g.
+    `api.add_resource(get_single_endpoint("Dataset"), "/datasets/<string:pid>")`
+
+    :param entity_name: Name of the entity
+    :type entity_name: :class:`str`
+    :return: Generated endpoint class
     """
 
     class EndpointWithID(Resource):
@@ -50,7 +62,13 @@ def get(self, pid):
 
 def get_number_count_endpoint(entity_name):
     """
-    TODO - Add docstring
+    Given an entity name, generate a flask_restful `Resource` class. In
+    `create_api_endpoints()`, these generated classes are registered with the API e.g.
+    `api.add_resource(get_number_count_endpoint("Dataset"), "/datasets/count")`
+
+    :param entity_name: Name of the entity
+    :type entity_name: :class:`str`
+    :return: Generated endpoint class
     """
 
     class CountEndpoint(Resource):
@@ -68,7 +86,13 @@ def get(self):
 
 def get_files_endpoint(entity_name):
     """
-    TODO - Add docstring
+    Given an entity name, generate a flask_restful `Resource` class. In
+    `create_api_endpoints()`, these generated classes are registered with the API e.g.
+    `api.add_resource(get_files_endpoint("Dataset"), "/datasets/<string:pid>/files")`
+
+    :param entity_name: Name of the entity
+    :type entity_name: :class:`str`
+    :return: Generated endpoint class
     """
 
     class FilesEndpoint(Resource):
@@ -85,7 +109,14 @@ def get(self, pid):
 
 def get_number_count_files_endpoint(entity_name):
     """
-    TODO - Add docstring
+    Given an entity name, generate a flask_restful `Resource` class. In
+    `create_api_endpoints()`, these generated classes are registered with the API e.g.
+    `api.add_resource(get_number_count_files_endpoint("Dataset"),
+    "/datasets<string:pid>/files/count")`
+
+    :param entity_name: Name of the entity
+    :type entity_name: :class:`str`
+    :return: Generated endpoint class
     """
 
     class CountFilesEndpoint(Resource):