From f34c5e7bcb29797be082f532655d45d29a8cce22 Mon Sep 17 00:00:00 2001
From: "Max P." <mail@0xMax42.io>
Date: Wed, 23 Jul 2025 13:38:59 +0200
Subject: [PATCH] docs(models): add docstrings for configuration and lock
 models

- Add detailed docstrings to configuration models, explaining attributes
- Improve clarity and maintainability of the codebase by documenting intent
- Ensure future developers understand the purpose of each model and field
---
 src/patchman/models/config.py | 17 +++++++++++++++++
 src/patchman/models/lock.py   | 10 ++++++++++
 2 files changed, 27 insertions(+)

diff --git a/src/patchman/models/config.py b/src/patchman/models/config.py
index 7b85027..1856135 100644
--- a/src/patchman/models/config.py
+++ b/src/patchman/models/config.py
@@ -3,14 +3,31 @@ from pydantic import BaseModel, Field, HttpUrl
 
 
 class UpstreamConfig(BaseModel):
+    """Configuration for the upstream repository.
+
+    Attributes:
+        url (HttpUrl): Git URL of the upstream repository.
+        branch (str): Upstream branch to track (default: 'main').
+    """
     url: HttpUrl = Field(..., description="Git URL of the upstream repository")
     branch: str = Field(default="main", description="Upstream branch to track (default: 'main')")
 
 
 class PatchesConfig(BaseModel):
+    """Configuration for the patch directory.
+
+    Attributes:
+        directory (str): Path to the patch directory.
+    """
     directory: str = Field(default="./patches", description="Path to patch directory")
 
 
 class PatchmanConfig(BaseModel):
+    """Main configuration for the Patchman application.
+
+    Attributes:
+        upstream (UpstreamConfig): Configuration for the upstream repository.
+        patches (PatchesConfig): Configuration for the patch directory.
+    """
     upstream: UpstreamConfig
     patches: PatchesConfig
diff --git a/src/patchman/models/lock.py b/src/patchman/models/lock.py
index b9d069d..376bce9 100644
--- a/src/patchman/models/lock.py
+++ b/src/patchman/models/lock.py
@@ -3,9 +3,19 @@ from typing import Literal
 
 
 class UpstreamLock(BaseModel):
+    """Represents the lock state of the upstream repository.
+
+    Attributes:
+        last_commit (str): Commit hash of the last processed upstream repository.
+    """
     last_commit: str = Field(..., min_length=40, max_length=40, pattern="^[0-9a-f]{40}$",
                              description="Commit hash of the last processed upstream repository")
 
 
 class PatchmanLock(BaseModel):
+    """Represents the lock state of the Patchman application.
+
+    Attributes:
+        upstream (UpstreamLock): Lock state of the upstream repository.
+    """
     upstream: UpstreamLock