From 182d05472e11ed0be7f0c837cb4cdd7dea21ac34 Mon Sep 17 00:00:00 2001
From: Matthew Richards <matthew.richards@stfc.ac.uk>
Date: Wed, 19 Aug 2020 11:36:46 +0000
Subject: [PATCH]  #140: Add docstrings

---
 common/icat/filters.py |  1 +
 common/icat/helpers.py | 22 ++++++++++++++++++++--
 2 files changed, 21 insertions(+), 2 deletions(-)

diff --git a/common/icat/filters.py b/common/icat/filters.py
index 2594aed4..191e012d 100644
--- a/common/icat/filters.py
+++ b/common/icat/filters.py
@@ -78,6 +78,7 @@ def apply_filter(self, query):
 
 
 class PythonICATOrderFilter(OrderFilter):
+    # Used to append the order tuples across all filters in a single request
     result_order = []
 
     def __init__(self, field, direction):
diff --git a/common/icat/helpers.py b/common/icat/helpers.py
index 0edb60ee..789817bf 100644
--- a/common/icat/helpers.py
+++ b/common/icat/helpers.py
@@ -361,8 +361,18 @@ def update_entity_by_id(client, table_name, id_, new_data):
 
 def get_entity_with_filters(client, table_name, filters):
     """
-    TODO - Add docstring
+    Gets all the records of a given entity, based on the filters provided in the request
+
+    :param client: ICAT client containing an authenticated user
+    :type client: :class:`icat.client.Client`
+    :param table_name: Table name to extract which entity to use
+    :type table_name: :class:`str`
+    :param filters: The list of filters to be applied to the request
+    :type filters: List of specific implementations :class:`QueryFilter`
+    :return: The list of records of the given entity, using the filters to restrict the
+        result of the query
     """
+
     selected_entity_name = get_python_icat_entity_name(client, table_name)
     query = construct_icat_query(client, selected_entity_name)
 
@@ -381,7 +391,15 @@ def get_entity_with_filters(client, table_name, filters):
 
 def manage_order_filters(filters):
     """
-    TODO - Add docstring
+    Checks if any order filters have been added to the request and resets the variable
+    used to manage which attribute(s) to use for sorting results.
+    
+    A reset is required because Python ICAT overwrites (as opposed to appending to it)
+    the query's order list every time one is added to the query.
+
+    :param filters: The list of filters to be applied to the request
+    :type filters: List of specific implementations :class:`QueryFilter`
     """
+
     if any(isinstance(filter, PythonICATOrderFilter) for filter in filters):
         PythonICATOrderFilter.result_order = []