@@ -54,6 +54,13 @@ class Summary:
 
 @dataclass(frozen=True, slots=True)
 class _PendingDocstring:
+    """Represent a definition and its pending docstring content.
+
+    Attributes:
+        definition (Definition): The definition associated with the docstring.
+        content (str): The docstring content.
+    """
+
     definition: Definition
     content: str
 
@@ -229,6 +236,21 @@ def _write_files(
     *,
     overwrite: bool,
 ) -> tuple[int, int]:
+    """Write pending docstrings to their source files.
+
+    Re-read each file and verify that pending definitions still match the source
+    before applying and writing docstrings. Log failures for files or definitions
+    that cannot be updated.
+
+    Args:
+        pending (dict[Path, list[_PendingDocstring]]): Docstrings to write,
+            grouped by source file.
+        overwrite (bool): Whether to include and replace existing docstrings.
+
+    Returns:
+        tuple[int, int]: The number of docstrings written and the number that
+        failed.
+    """
     written = 0
     failed = 0
     for path, items in sorted(pending.items()):
@@ -291,6 +313,13 @@ def _write_files(
 
 
 def _write_source(path: Path, source: str, encoding: str) -> None:
+    """Write source text to a file using a temporary replacement.
+
+    Args:
+        path (Path): Destination file path.
+        source (str): Text to write.
+        encoding (str): Encoding used to convert the text to bytes.
+    """
     data = source.encode(encoding)
     descriptor, temporary_name = tempfile.mkstemp(
         dir=path.parent,
 
@@ -85,11 +85,28 @@ class OpenRouterTransport:
     """A BatchTransport backed by the OpenRouter Python SDK."""
 
     def __init__(self, client: OpenRouter, model: str) -> None:
+        """Initialize the transport with an OpenRouter client and model.
+
+        Args:
+            client (OpenRouter): The OpenRouter client to use.
+            model (str): The model identifier.
+        """
         _ensure_batch_body_field_order()
         self._client = client
         self._model = model
 
     def create(self, requests: Sequence[BatchRequest]) -> BatchSubmission:
+        """Submit chat completion requests as an OpenRouter batch.
+
+        Args:
+            requests (Sequence[BatchRequest]): Requests to include in the batch.
+
+        Returns:
+            BatchSubmission: The submitted batch.
+
+        Raises:
+            BatchError: If batch submission fails.
+        """
         try:
             batch = self._client.batch.create_batches(
                 endpoint="/v1/chat/completions",
@@ -111,6 +128,17 @@ def create(self, requests: Sequence[BatchRequest]) -> BatchSubmission:
         return _to_submission(batch)
 
     def fetch(self, batch_id: str) -> BatchSubmission:
+        """Fetch a batch submission by its identifier.
+
+        Args:
+            batch_id (str): Identifier of the batch to fetch.
+
+        Returns:
+            BatchSubmission: The fetched batch submission.
+
+        Raises:
+            BatchError: If the batch cannot be fetched.
+        """
         try:
             batch = self._client.batch.get_batches(id=batch_id)
         except Exception as exc:
@@ -120,6 +148,14 @@ def fetch(self, batch_id: str) -> BatchSubmission:
 
 @dataclass(frozen=True, slots=True)
 class _PendingBatch:
+    """Represent a batch awaiting completion.
+
+    Attributes:
+        requests (tuple[BatchRequest, ...]): Requests included in the batch.
+        submission (BatchSubmission): Submission associated with the batch.
+        deadline (float): Deadline for the batch.
+    """
+
     requests: tuple[BatchRequest, ...]
     submission: BatchSubmission
     deadline: float
@@ -206,16 +242,42 @@ def run_batches(
 
 
 def _chunks(requests: Sequence[BatchRequest], size: int) -> list[list[BatchRequest]]:
+    """Split requests into chunks of the specified size.
+
+    Args:
+        requests (Sequence[BatchRequest]): Requests to split.
+        size (int): Maximum number of requests per chunk.
+
+    Returns:
+        list[list[BatchRequest]]: The requests grouped into chunks.
+    """
     return [list(requests[start : start + size]) for start in range(0, len(requests), size)]
 
 
 def _is_complete(submission: BatchSubmission) -> bool:
+    """Check whether a batch submission is complete.
+
+    Args:
+        submission (BatchSubmission): Submission to check.
+
+    Returns:
+        bool: Whether the submission has a final status and, if completed, has results.
+    """
     if submission.status not in FINAL_STATUSES:
         return False
     return not (submission.status == "completed" and submission.results is None)
 
 
 def _collect(item: _PendingBatch, results: dict[str, BatchResult]) -> None:
+    """Collect results for a completed batch or record failures for an unsuccessful one.
+
+    Args:
+        item (_PendingBatch): Pending batch containing the submission and its requests.
+        results (dict[str, BatchResult]): Mapping to update with results keyed by custom ID.
+
+    Returns:
+        None: Results are added to the supplied mapping.
+    """
     submission = item.submission
     if submission.status != "completed":
         detail = f": {submission.error}" if submission.error else ""
@@ -242,13 +304,30 @@ def _failures(
     requests: Sequence[BatchRequest],
     message: str,
 ) -> dict[str, BatchResult]:
+    """Build an error result for each request.
+
+    Args:
+        requests (Sequence[BatchRequest]): Requests to create error results for.
+        message (str): Error message to assign to each result.
+
+    Returns:
+        dict[str, BatchResult]: Error results keyed by request custom ID.
+    """
     return {
         request.custom_id: BatchResult(custom_id=request.custom_id, error=message)
         for request in requests
     }
 
 
 def _to_submission(batch: BatchObject) -> BatchSubmission:
+    """Convert a batch object to a submission.
+
+    Args:
+        batch (BatchObject): Batch object to convert.
+
+    Returns:
+        BatchSubmission: Submission containing the batch ID and status, converted results if present, and the error message if present.
+    """
     results = None
     if batch.results is not None:
         results = tuple(_to_result(result) for result in batch.results)
@@ -257,12 +336,28 @@ def _to_submission(batch: BatchObject) -> BatchSubmission:
 
 
 def _to_result(result: Result) -> BatchResult:
+    """Convert a result to a batch result.
+
+    Args:
+        result (Result): The result to convert.
+
+    Returns:
+        BatchResult: A result containing the error message if an error is present, or the chat content otherwise.
+    """
     if result.error is not None:
         return BatchResult(custom_id=result.custom_id, error=result.error.message)
     return BatchResult(custom_id=result.custom_id, content=_chat_content(result))
 
 
 def _chat_content(result: Result) -> str | None:
+    """Extract the first nonempty chat completion message.
+
+    Args:
+        result (Result): The result containing a response to inspect.
+
+    Returns:
+        str | None: The first nonempty message content, or `None` if no chat completion content is available.
+    """
     if result.response is None:
         return None
     body = result.response.body
 
@@ -51,6 +51,19 @@ def main(argv: Sequence[str] | None = None) -> int:
 
 
 def _run(args: argparse.Namespace) -> Summary:
+    """Run documentation generation using the supplied command-line arguments.
+
+    Args:
+        args (argparse.Namespace): Options for the folder, model, polling interval,
+            timeout, batch size, overwrite behavior, and dry-run mode.
+
+    Returns:
+        Summary: The result returned by `document_folder`.
+
+    Raises:
+        ConfigurationError: If `OPENROUTER_API_KEY` is not set and dry-run mode is
+            disabled.
+    """
     options = {
         "poll_interval": args.poll_interval,
         "timeout": args.timeout_hours * 3600,
@@ -71,6 +84,11 @@ def _run(args: argparse.Namespace) -> Summary:
 
 
 def _print_summary(summary: Summary) -> None:
+    """Print a summary of the documentation run.
+
+    Args:
+        summary (Summary): Counts and status details for the documentation run.
+    """
     files = pluralize(summary.files, "file", "files")
     definitions = pluralize(summary.definitions, "definition", "definitions")
     docstrings = pluralize(summary.written, "docstring", "docstrings")
@@ -92,6 +110,13 @@ def _print_summary(summary: Summary) -> None:
 
 
 def _build_parser() -> argparse.ArgumentParser:
+    """Build and return the command-line argument parser.
+
+    The parser defines options for the folder to scan, model, batch polling and timeout settings, batch size, overwriting docstrings, dry runs, and quiet output.
+
+    Returns:
+        argparse.ArgumentParser: The configured argument parser.
+    """
     parser = argparse.ArgumentParser(
         prog="add-docstrings",
         description=(
 
@@ -62,26 +62,72 @@ def discover_source(
 
 
 class _Collector(ast.NodeVisitor):
+    """Collect definitions while traversing an abstract syntax tree.
+
+    Records classes, functions, and methods, including nested definitions. Documented definitions are included only when `include_documented` is enabled.
+
+    Attributes:
+        definitions (list[Definition]): Definitions collected during traversal.
+    """
+
     def __init__(self, path: Path, lines: list[str], *, include_documented: bool) -> None:
+        """Initialize the collector state.
+
+        Args:
+            path (Path): Source file path.
+            lines (list[str]): Lines of source code.
+            include_documented (bool): Whether to include documented definitions.
+        """
         self._path = path
         self._lines = lines
         self._include_documented = include_documented
         self._scopes: list[DefinitionNode] = []
         self.definitions: list[Definition] = []
 
     def visit_ClassDef(self, node: ast.ClassDef) -> None:
+        """Record a class definition and visit its contents.
+
+        Args:
+            node (ast.ClassDef): The class definition to record and traverse.
+
+        Returns:
+            None: This method does not return a value.
+        """
         self._record(node, "class")
         self._scopes.append(node)
         self.generic_visit(node)
         self._scopes.pop()
 
     def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        """Delegate a function definition node to the function visitor.
+
+        Args:
+            node (ast.FunctionDef): Function definition node to visit.
+        """
         self._visit_function(node)
 
     def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+        """Visit an asynchronous function definition.
+
+        Args:
+            node (ast.AsyncFunctionDef): The function definition to visit.
+
+        Returns:
+            None: This method does not return a value.
+        """
         self._visit_function(node)
 
     def _visit_function(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
+        """Record and traverse a function definition.
+
+        Classify the definition as a method when the current scope is a class, otherwise as a function. Add it to the scope while visiting its contents.
+
+        Args:
+            node (ast.FunctionDef | ast.AsyncFunctionDef): The function definition to visit.
+
+        Returns:
+            None
+        """
         kind: DefinitionKind = (
             "method" if self._scopes and isinstance(self._scopes[-1], ast.ClassDef) else "function"
         )
@@ -91,6 +137,15 @@ def _visit_function(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
         self._scopes.pop()
 
     def _record(self, node: DefinitionNode, kind: DefinitionKind) -> None:
+        """Record a definition unless documented definitions are excluded.
+
+        Args:
+            node (DefinitionNode): Definition node to record.
+            kind (DefinitionKind): Kind of definition to record.
+
+        Returns:
+            None: This method does not return a value.
+        """
         has_docstring = ast.get_docstring(node, clean=False) is not None
         if has_docstring and not self._include_documented:
             return