📝 Add docstrings to add-include-package-data

Docstrings generation was requested by @shenxianpeng.

* #138 (comment)

The following files were modified:

* `cpp_linter_hooks/clang_format.py`
* `cpp_linter_hooks/clang_tidy.py`
* `cpp_linter_hooks/util.py`

Author: coderabbitai[bot]

cpp_linter_hooks/clang_format.py

@@ -14,6 +14,20 @@
 
 
 def run_clang_format(args=None) -> Tuple[int, str]:
+    """
+    Run clang-format with the given arguments and return its exit code and combined output.
+    
+    Parses known hook options from `args`, optionally ensures a specific clang-format version is installed, builds and executes a clang-format command (modifying files in-place by default), and captures stdout and stderr merged into a single output string.
+    
+    Parameters:
+        args (Optional[Sequence[str]]): Argument list to parse (typically sys.argv[1:]). If omitted, uses parser defaults.
+    
+    Returns:
+        tuple[int, str]: A pair (retval, output) where `output` is the concatenation of stdout and stderr.
+            `retval` is the subprocess return code, except:
+            - `-1` when the command included `--dry-run` (special sentinel to indicate dry-run mode),
+            - `1` when clang-format could not be found (FileNotFoundError converted to an exit-like code).
+    """
     hook_args, other_args = parser.parse_known_args(args)
     if hook_args.version:
         resolve_install("clang-format", hook_args.version)
@@ -73,4 +87,4 @@ def main() -> int:
 
 
 if __name__ == "__main__":
-    raise SystemExit(main())
+    raise SystemExit(main())

cpp_linter_hooks/clang_tidy.py

@@ -10,6 +10,17 @@
 
 
 def run_clang_tidy(args=None) -> Tuple[int, str]:
+    """
+    Run clang-tidy with the given command-line arguments and return a status code and captured output.
+    
+    Parameters:
+        args (Optional[Sequence[str]]): Arguments to parse and forward to clang-tidy; if None, uses sys.argv. If the parsed arguments include a --version value, the specified clang-tidy version is ensured to be installed before running.
+    
+    Returns:
+        Tuple[int, str]: A pair (status, output).
+            - status: 0 when clang-tidy executed and produced no warnings or errors; 1 when clang-tidy reports any "warning:" or "error:", or when clang-tidy cannot be executed.
+            - output: Captured stdout from clang-tidy, or the error text if execution failed.
+    """
     hook_args, other_args = parser.parse_known_args(args)
     if hook_args.version:
         resolve_install("clang-tidy", hook_args.version)
@@ -37,4 +48,4 @@ def main() -> int:
 
 
 if __name__ == "__main__":
-    raise SystemExit(main())
+    raise SystemExit(main())

cpp_linter_hooks/util.py

@@ -60,7 +60,16 @@ def parse_version(v: str):
 
 
 def _install_tool(tool: str, version: str) -> Optional[Path]:
-    """Install a tool using pip, suppressing output."""
+    """
+    Install the specified tool version into the current Python environment and return its executable path.
+    
+    Parameters:
+        tool (str): The package/executable name to install (e.g., "clang-format").
+        version (str): The exact version string to install (e.g., "14.0.6").
+    
+    Returns:
+        Path: Path to the installed tool's executable if the installation succeeds and the executable is found, `None` otherwise.
+    """
     try:
         subprocess.check_call(
             [sys.executable, "-m", "pip", "install", f"{tool}=={version}"],
@@ -73,7 +82,16 @@ def _install_tool(tool: str, version: str) -> Optional[Path]:
 
 
 def resolve_install(tool: str, version: Optional[str]) -> Optional[Path]:
-    """Resolve the installation of a tool, checking for version and installing if necessary."""
+    """
+    Resolve and install the requested clang tool version and return its executable path.
+    
+    Parameters:
+        tool (str): Tool name, expected "clang-format" or "clang-tidy".
+        version (Optional[str]): Desired version string (exact match or prefix). If None, falls back to the default version from pyproject.toml when available.
+    
+    Returns:
+        Optional[Path]: Path to the installed tool executable if installation succeeded, `None` otherwise.
+    """
     user_version = _resolve_version(
         CLANG_FORMAT_VERSIONS if tool == "clang-format" else CLANG_TIDY_VERSIONS,
         version,
@@ -85,4 +103,4 @@ def resolve_install(tool: str, version: Optional[str]) -> Optional[Path]:
             else DEFAULT_CLANG_TIDY_VERSION
         )
 
-    return _install_tool(tool, user_version)
+    return _install_tool(tool, user_version)