Add docstring and type hints for script

Author: XuhuaHuang

Scripts/clang_format_cli.py

@@ -1,6 +1,5 @@
 """
 Batch format C/C++ files using clang-format.
-This script searches for C/C++ source files in the specified directories and formats them using clang-format.
 """
 
 import argparse
@@ -9,6 +8,15 @@
 
 
 def is_in_site_packages(path: pathlib.Path) -> bool:
+    """
+    Check if the given path is in a site-packages directory.
+
+    Args:
+        path (pathlib.Path): The path to check for site-packages.
+
+    Returns:
+        bool: True if the path is in a site-packages directory, False otherwise.
+    """
     # Normalize path parts for cross-platform matching
     lower_parts = [part.lower() for part in path.parts]
     return (
@@ -17,7 +25,16 @@ def is_in_site_packages(path: pathlib.Path) -> bool:
     )
 
 
-def is_standalone_source_file(path):
+def is_standalone_source_file(path: pathlib.Path) -> bool:
+    """
+    Check if the given path is a standalone source file.
+
+    Args:
+        path (pathlib.Path): The path to check.
+
+    Returns:
+        bool: True if the path is a standalone source file, False otherwise.
+    """
     # Heuristics for standalone source file
     if not path.is_file():
         return False
@@ -27,16 +44,26 @@ def is_standalone_source_file(path):
         return False  # skip virtual environments
     if "build" in path.parts or "out" in path.parts:
         return False  # skip build outputs
-    if any(x in path.name.lower() for x in ["generated files", "build", "lib", "generated", "autogen", "moc_", "ui_"]):
+    if any(x in path.name.lower() for x in ["build", "lib", "generated", "autogen", "moc_", "ui_"]):
         return False  # skip generated files
     # Assume headers are not standalone sources
     # if path.suffix in [".h", ".hpp"]:
     #     return False
     return True
 
 
-def find_files(paths, extensions) -> list[pathlib.Path]:
-    files = []
+def find_files(paths: list[pathlib.Path], extensions: set[str]) -> list[pathlib.Path]:
+    """
+    Find all files in the given paths with the specified extensions.
+
+    Args:
+        paths (list[pathlib.Path]): The directories to search for files.
+        extensions (set[str]): The file extensions to include in the search.
+
+    Returns:
+        list[pathlib.Path]: A list of found files with the specified extensions.
+    """
+    files: list[pathlib.Path] = []
     for path in paths:
         root = pathlib.Path(path).resolve()
         if not root.exists():
@@ -51,7 +78,16 @@ def find_files(paths, extensions) -> list[pathlib.Path]:
     return files
 
 
-def check_clang_format_config(start_paths):
+def check_clang_format_config(start_paths: list[str]) -> bool:
+    """
+    Check if a .clang-format file exists in specified or parent directories.
+
+    Args:
+        start_paths (pathlib.Path): The directories to search for .clang-format files.
+
+    Returns:
+        bool: True if a .clang-format file is found, False otherwise.
+    """
     for path in start_paths:
         dir_path = pathlib.Path(path).resolve()
         for parent in [*dir_path.parents, dir_path]:
@@ -60,7 +96,14 @@ def check_clang_format_config(start_paths):
     return False
 
 
-def format_files(files):
+def format_files(files: list[pathlib.Path]) -> None:
+    """
+    Format the given files using clang-format.
+    This function runs clang-format on each file and prints the progress.
+
+    Args:
+        files (list[pathlib.Path]): The list of files to format.
+    """
     total = len(files)
     for i, file_path in enumerate(files, start=1):
         percent = int((i / total) * 100)
@@ -72,6 +115,9 @@ def format_files(files):
 
 
 def main():
+    """
+    Main function to parse command-line arguments and format files.
+    """
     parser = argparse.ArgumentParser(
         description="Batch format C/C++ files using clang-format."
     )
@@ -105,7 +151,7 @@ def main():
     args = parser.parse_args()
 
     if not check_clang_format_config(args.paths):
-        print("⚠️  Warning: No .clang-format file found in the specified paths or their parent directories.\n")
+        print("⚠️  Warning: No .clang-format file found in specified or parent directories.\n")
 
     files = find_files(args.paths, set(args.extensions))