DOC: update search method docstrings

superscore/backends/core.py

@@ -45,7 +45,18 @@ def update_entry(self, entry: Entry) -> None:
         raise NotImplementedError
 
     def search(self, *search_terms) -> Generator[Entry, None, None]:
-        """Yield Entry objects matching all ``search_terms``"""
+        """
+        Yield Entry objects matching all ``search_terms``. Each SearchTerm has the format
+        (<attr>, <operator>, <value>).  Some operators take tuples as values.
+
+        The supported operators are:
+        - eq (equals)
+        - lt (less than or equal to)
+        - gt (greater than or equal to)
+        - in
+        - in_range (takes (<lower>, <upper>) as value)
+        - like (fuzzy match, depends on type of value)
+        """
         raise NotImplementedError
 
     @property

superscore/backends/filestore.py

@@ -287,10 +287,9 @@ def delete_entry(self, entry: Entry) -> None:
 
     def search(self, *search_terms) -> Generator[Entry, None, None]:
         """
-        Search for an entry that matches ``search_kwargs``.
-        Keys are attributes on `Entry` subclasses
-        Values can be either a single value to match or a tuple of valid values
-        Currently does not support partial matches.
+        Return entries that match all ``search_terms``.
+        Keys are attributes on `Entry` subclasses, or special keywords.
+        Values can be a single value or a tuple of values depending on operator.
         """
         with self._load_and_store_context() as db:
             for entry in db.values():
@@ -312,18 +311,20 @@ def search(self, *search_terms) -> Generator[Entry, None, None]:
     @staticmethod
     def getComparator(op: str, typ: type) -> Callable[[Any, Any], bool]:
         """
+        Return a function that applies the comparator ``op`` to two args. The function
+        may depend on the type of the args ``typ``
+
         Parameters
         ----------
         op: str
-            one of the comparators that all backends must support, consisting of
-            'eq', 'lt', 'gt', 'like', and 'in'
+            one of the comparators that all backends must support, detailed in _Backend.search
         typ: type
-            the type that the comparator must operate on
+            the type that the comparator will operate on
 
         Returns
         -------
         Callable
-            a function that compares two values with type typ according to op
+            a function that compares two values according to ``op``
         """
         if op == "eq":
             return typ.__eq__

superscore/client.py

@@ -148,7 +148,12 @@ def find_config() -> Path:
         raise OSError("No superscore configuration file found. Check SUPERSCORE_CFG.")
 
     def search(self, *post) -> Generator[Entry, None, None]:
-        """Search by SearchTerm.  Can search by any field, plus special flags"""
+        """
+        Search backend for entries matching all SearchTerms in ``post``.  Can search by any
+        field, plus some special keywords. Backends support operators listed in _Backend.search.
+        Some operators are supported in the UI / client and must be converted before being
+        passed to the backend.
+        """
         new_search_terms = []
         for search_term in post:
             if search_term.operator == 'like_with_tols':