main doc done

app/__init__.py

@@ -13,3 +13,4 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
+"""The NLP API app."""

app/__main__.py

@@ -13,6 +13,7 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
+"""Start the NLP API app server."""
 import argparse
 import os
 import traceback
@@ -30,6 +31,12 @@
 
 
 def parse_args() -> argparse.Namespace:
+    """
+    Parses command line arguments.
+
+    Returns:
+        argparse.Namespace: The arguments.
+    """
     parser = argparse.ArgumentParser(
         prog=f"python -m {python_module()}",
         description="Run the API server")
@@ -55,6 +62,7 @@ def parse_args() -> argparse.Namespace:
 
 
 def run() -> None:
+    """Start the app server."""
     args = parse_args()
     env_file: str | None = args.env
     if env_file:

app/system/config.py

@@ -16,7 +16,7 @@
 """The app configuration."""
 import json
 import os
-from typing import cast, TYPE_CHECKING, TypedDict
+from typing import cast, NoReturn, TYPE_CHECKING, TypedDict
 
 from app.misc.env import envload_bool, envload_int, envload_path, envload_str
 from app.misc.io import open_read, open_write
@@ -39,13 +39,22 @@
     "write_token": str,
     "tanuki": str,
 })
+"""The config object."""
 
 
 CONFIG: Config | None = None
+"""The cached config object."""
 CONFIG_PATH: str | None = None
+"""The cached config path."""
 
 
 def get_config_path() -> str:
+    """
+    Reads the config path from the environment.
+
+    Returns:
+        str: The path.
+    """
     global CONFIG_PATH  # pylint: disable=global-statement
 
     if CONFIG_PATH is None:
@@ -54,6 +63,12 @@ def get_config_path() -> str:
 
 
 def config_template() -> Config:
+    """
+    Create a config template.
+
+    Returns:
+        Config: The config template.
+    """
     default_conn: 'DBConfig' = {
         "dialect": "postgresql",
         "host": "localhost",
@@ -90,7 +105,16 @@ def config_template() -> Config:
     }
 
 
-def create_config_and_err(config_path: str) -> None:
+def create_config_and_err(config_path: str) -> NoReturn:
+    """
+    Creates a config template, writes it to the path and then errors out.
+
+    Args:
+        config_path (str): _description_
+
+    Raises:
+        ValueError: _description_
+    """
     with open_write(config_path, text=True) as fout:
         print(
             json.dumps(config_template(), indent=4, sort_keys=True),
@@ -102,6 +126,12 @@ def create_config_and_err(config_path: str) -> None:
 
 
 def get_config() -> Config:
+    """
+    Load the config.
+
+    Returns:
+        Config: The config object.
+    """
     global CONFIG  # pylint: disable=global-statement
 
     if CONFIG is not None:

app/system/stats.py

@@ -13,14 +13,24 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
+"""Compute usage statistics of certain NLP APIs."""
 from collections.abc import Callable
 
 
 LengthCounter = Callable[[str], str]
+"""Adds the length of the text to the length counter. Returns the text."""
 LengthResult = Callable[[], int]
+"""Returns the current total of the length counter."""
 
 
 def create_length_counter() -> tuple[LengthCounter, LengthResult]:
+    """
+    Creates a length counter pair.
+
+    Returns:
+        tuple[LengthCounter, LengthResult]: The counter to count processing
+            amount and a function to retrieve the result.
+    """
     total = 0
 
     def length_counter(text: str) -> str: