refine docs and code comments/format

Author: Gerit Wagner

docs/source/automate.rst

@@ -47,7 +47,7 @@ Using the Crossref API as an example, the following illustrates how to construct
 
    if __name__ == "__main__":
 
-       query = OrQuery(["microsourcing", "lululemon"], field="title")
+       query = OrQuery(["microsourcing", "online labor markets"], field="title")
 
        url = to_crossref_url(query)
        api_crossref = crossref_api.CrossrefAPI(url=url)
@@ -56,15 +56,14 @@ Using the Crossref API as an example, the following illustrates how to construct
        sf = SearchFile(
            search_string=query.to_string(),
            platform="crossref",
-           authors=[{"name": "Tom Brady"}],
+           authors=[{"name": "Gerit Wagner"}],
            record_info={"source": "manual", "url": url},
            date={"data_entry": datetime.datetime.now().strftime("%Y-%m-%d %H:%M")},
            field="title",
-           description="Search for work authored by Tom Brady",
-           tags=["microsourcing", "lululemon", "research"]
+           description="Search for research on microsourcing"
        )
 
-       sf.save("test/tom_brady_search.json")
+       sf.save("test/microsourcing_search.json")
 
        records_dict = {record.get_value("doi"): record.get_data() for record in records}
        write_file(records_dict=records_dict, filename=Path("test/crossref_records.bib"))

docs/source/dev_docs/_autosummary/search_query.parser_base.rst

@@ -9,4 +9,5 @@ search\_query.parser\_base
    .. autosummary::
 
       QueryListParser
+      QueryParserBase
       QueryStringParser

docs/source/index.rst

@@ -47,7 +47,7 @@ Creating a query programmatically is simple:
     work_synonyms = OrQuery(["work", "labor", "service"], field="abstract")
     query = AndQuery([digital_synonyms, work_synonyms])
 
-A query can also be parsed from a string or a `JSON search file <#json-search-files>`_ (see the :doc:`overview of platform identifiers </platforms/platform_index>`):
+A query can also be parsed from a string or a `JSON search file <load.html#file>`_ (see the :doc:`overview of platform identifiers </platforms/platform_index>`):
 
 .. code-block:: python
 

docs/source/load.rst

@@ -5,11 +5,25 @@ Load
 
 Queries can be loaded from strings/files, defined as objects, or retrieved from the internal database.
 
-String/file
+String
 -------------------------
 
-Search-query can parse queries from strings and JSON query files.
-To load a JSON query file, run the parser:
+Search-query can parse queries from strings.
+To load a query from a string, run:
+
+.. code-block:: python
+
+   from search_query.parser import parse
+
+   query_string = '("digital health"[Title/Abstract]) AND ("privacy"[Title/Abstract])'
+   query = parse(query_string, platform="pubmed")
+
+
+File
+-------------------------
+
+Search-query can parse queries from JSON query files.
+To load a JSON query file, run:
 
 .. code-block:: python
 

search_query/linter_base.py

@@ -1241,7 +1241,8 @@ def _highlight_removed_chars(self, original: str, modified: str) -> str:
             # skip added characters ('+')
         return result
 
-    # TODO : 10.1079_SEARCHRXIV.2023.00129.json , 10.1079_SEARCHRXIV.2023.00269.json ,
+    # Examples:
+    # 10.1079_SEARCHRXIV.2023.00129.json , 10.1079_SEARCHRXIV.2023.00269.json ,
     # 10.1079_SEARCHRXIV.2024.00457.json- position mismtach
     def _check_unnecessary_nesting(self, query: Query) -> None:
         """Check for unnecessary same-operator nesting and provide simplification advice."""
@@ -1454,7 +1455,6 @@ def _check_for_wildcard_usage(self, term_field_query: Query) -> None:
             return
 
         if term_field_query.value == "OR" and term_field_query.operator:
-            # TODO : consider search-fields!
             term_objects = [
                 child for child in term_field_query.children if child.is_term()
             ]

search_query/wos/linter.py

@@ -444,8 +444,6 @@ def check_deprecated_field_tags(self, query: Query) -> None:
             if not query.field:
                 return
 
-            # TODO: clarify advice... + context (called via CI / with filename?)
-
             # use of the following field tags in the search interface prints
             # Search Error: Invalid field tag.
             if query.field.value in [

search_query/wos/translator.py

@@ -3,8 +3,9 @@
 from __future__ import annotations
 
 import re
-from search_query.constants import PLATFORM
+
 from search_query.constants import Fields
+from search_query.constants import PLATFORM
 from search_query.query import Query
 from search_query.query import SearchField
 from search_query.query_or import OrQuery