From d852bda091411e355c7d62832f82921a077fdfec Mon Sep 17 00:00:00 2001
From: luxferre <chris@sr2.uk>
Date: Thu, 28 May 2026 14:41:11 +0100
Subject: [PATCH] docs: service docstrings

Issue: #13
---
 src/service/config.py       |  6 +-----
 src/service/constants.py    |  6 +-----
 src/service/dependencies.py | 12 ++++--------
 src/service/exceptions.py   |  5 ++---
 src/service/models.py       |  4 ++--
 src/service/router.py       |  8 +++++---
 src/service/schemas.py      |  9 +++++----
 src/service/service.py      | 10 +---------
 src/service/utils.py        | 11 +++--------
 9 files changed, 24 insertions(+), 47 deletions(-)

diff --git a/src/service/config.py b/src/service/config.py
index 4be170e..5d4fd3b 100644
--- a/src/service/config.py
+++ b/src/service/config.py
@@ -1,7 +1,3 @@
 """
-Configurations for <this module>
-
-Configurations:
- - List: Description
- - Configs: Description
+Configurations for the services module
 """
\ No newline at end of file
diff --git a/src/service/constants.py b/src/service/constants.py
index e1df957..52a8701 100644
--- a/src/service/constants.py
+++ b/src/service/constants.py
@@ -1,7 +1,3 @@
 """
-Constants and error codes for <this module>
-
-Constants:
- - List: Description
- - Consts: Description
+Constants for the services module
 """
\ No newline at end of file
diff --git a/src/service/dependencies.py b/src/service/dependencies.py
index d649b06..cda625a 100644
--- a/src/service/dependencies.py
+++ b/src/service/dependencies.py
@@ -1,13 +1,9 @@
 """
-Router dependencies for <this module>
+Dependencies related to the services module
 
-Classes:
- - List: Description
- - Classes: Description
-
-Functions:
- - List: Description
- - Functions: Description
+Exports:
+ - service_model_query_dependency: service_model: Gets service model from db, if it exists. Uses service_id from query param.
+ - service_model_body_dependency: service_model: Gets service model from db, if it exists. Uses service_id from request body.
 """
 from typing import Annotated
 from fastapi import Depends, Query
diff --git a/src/service/exceptions.py b/src/service/exceptions.py
index e2b5232..8a1a2e3 100644
--- a/src/service/exceptions.py
+++ b/src/service/exceptions.py
@@ -1,9 +1,8 @@
 """
-Module specific exceptions for <this module>
+Exceptions related to the services module
 
 Exceptions:
- - List: Description
- - Exceptions: Description
+ - ServiceNotFoundException: Takes an optional service_id int
 """
 from typing import Optional
 
diff --git a/src/service/models.py b/src/service/models.py
index 3f05e1d..68fd020 100644
--- a/src/service/models.py
+++ b/src/service/models.py
@@ -2,8 +2,8 @@
 Database models for the services module
 
 Models:
- - List: Description
- - Models: Description
+ - Service:
+  - id[PK], name[U], api_key[U]
 """
 from sqlalchemy import Column, Integer, String
 
diff --git a/src/service/router.py b/src/service/router.py
index f53d666..bf01a87 100644
--- a/src/service/router.py
+++ b/src/service/router.py
@@ -1,9 +1,11 @@
 """
-Router endpoints for <this module>
+Router endpoints for the services module
 
 Endpoints:
- - List: Description
- - Endpoints: Description
+ - [GET](/): [root user]: Get a list of all services(id, name)
+ - [POST](/): [super admin]: Register a new service(name) on the hub, returns the API key for the service to access the hub.
+ - [PATCH](/key): [super_admin]: Refreshes the API key for a service(id), returning a new one.
+ - [DELETE](/): [super_admin]: Removes a service(id) from the hub.
 """
 from fastapi import APIRouter, status
 from psycopg.errors import UniqueViolation
diff --git a/src/service/schemas.py b/src/service/schemas.py
index d6f2882..2d89400 100644
--- a/src/service/schemas.py
+++ b/src/service/schemas.py
@@ -1,9 +1,10 @@
 """
-Pydantic models for the service module
+Pydantic models for service module
 
-Models:
- - List: Description
- - Models: Description
+Models follow the nomenclature of:
+- Sub-models: "<Resource><Opt:>Schema"
+- Mixins: "<Attribute>Mixin"
+- Models: "<Module><Method><Resource><Opt:Resource><Direction>" ie "ServiceGetServiceResponse"
 """
 from pydantic import ConfigDict
 
diff --git a/src/service/service.py b/src/service/service.py
index 7365fa9..2609565 100644
--- a/src/service/service.py
+++ b/src/service/service.py
@@ -1,11 +1,3 @@
 """
-Module specific business logic for <this module>
-
-Classes:
- - List: Description
- - Classes: Description
-
-Functions:
- - List: Description
- - Functions: Description
+Business logic for the services module
 """
\ No newline at end of file
diff --git a/src/service/utils.py b/src/service/utils.py
index ecd41b0..8920a5f 100644
--- a/src/service/utils.py
+++ b/src/service/utils.py
@@ -1,13 +1,8 @@
 """
-Non-business logic reusable functions and classes for <this module>
+Non-business logic reusable functions and classes for the services module
 
-Classes:
- - List: Description
- - Classes: Description
-
-Functions:
- - List: Description
- - Functions: Description
+Exports:
+ - generate_api_key(): returns a new UUID
 """
 import uuid