📝 Add docstrings to docs/mkdocs-site

src/mcp_github_pr_review_spec_maker/cli.py

@@ -14,6 +14,18 @@
 
 
 def _positive_int(value: str) -> int:
+    """
+    Validate and convert a string to a positive integer.
+
+    Parameters:
+        value (str): String to parse as an integer.
+
+    Returns:
+        int: The parsed integer greater than zero.
+
+    Raises:
+        argparse.ArgumentTypeError: If `value` cannot be parsed as an integer or if the parsed integer is not greater than zero.
+    """
     try:
         ivalue = int(value)
     except ValueError as exc:  # pragma: no cover - argparse handles messaging
@@ -24,6 +36,20 @@ def _positive_int(value: str) -> int:
 
 
 def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    """
+    Parse command-line arguments for the MCP GitHub PR Review Spec server.
+
+    Parameters:
+        argv (list[str] | None): Optional list of argument strings to parse. If None, the program's arguments are parsed.
+
+    Returns:
+        argparse.Namespace: Parsed arguments with fields:
+            - env_file (Path | None): Path to a .env file to load, if provided.
+            - max_pages (int | None): Override for PR_FETCH_MAX_PAGES.
+            - max_comments (int | None): Override for PR_FETCH_MAX_COMMENTS.
+            - per_page (int | None): Override for HTTP_PER_PAGE.
+            - max_retries (int | None): Override for HTTP_MAX_RETRIES.
+    """
     parser = argparse.ArgumentParser(
         prog="mcp-github-pr-review-spec-maker",
         description="Run the GitHub PR Review Spec MCP server over stdio.",
@@ -57,6 +83,15 @@ def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
 
 
 def main(argv: list[str] | None = None) -> int:
+    """
+    Run the CLI entrypoint: load environment variables (optionally from a file), apply any CLI-provided overrides, start the ReviewSpecGenerator server, and return an appropriate exit code.
+
+    Parameters:
+        argv (list[str] | None): Command-line arguments to parse; if None, defaults to typical CLI invocation (parse_args will use sys.argv).
+
+    Returns:
+        int: Process exit code — `0` on normal completion, `130` if interrupted by KeyboardInterrupt; other exceptions are re-raised.
+    """
     args = parse_args(argv)
 
     if args.env_file:
@@ -86,4 +121,4 @@ def main(argv: list[str] | None = None) -> int:
 
 
 if __name__ == "__main__":  # pragma: no cover
-    raise SystemExit(main())
+    raise SystemExit(main())