audit_function_docs.py File Reference

Audits C and Python function documentation coverage across the repository. More...

Go to the source code of this file.

Data Structures
class	audit_function_docs.AuditFinding
	Represents one audit failure. More...

Namespaces
namespace	audit_function_docs

Functions
list[Path]	audit_function_docs._iter_c_files (tuple[Path,...] directories)
	Returns all C or header files below the configured directories.
list[Path]	audit_function_docs._iter_python_files ()
	Returns all Python source files covered by the audit.
list[str]	audit_function_docs._read_lines (Path path)
	Reads a text file into a list of lines.
str	audit_function_docs._relative_path (Path path)
	Returns a repository-relative path string.
tuple[int, int]|None	audit_function_docs._find_attached_doxygen_block (list[str] lines, int start_line)
	Finds the Doxygen block immediately attached to a declaration or definition.
list[str]	audit_function_docs._split_c_parameters (str signature)
	Splits a C signature parameter list into parameter names.
str	audit_function_docs._c_return_type (str signature, str symbol)
	Extracts the declared C return type prefix for one signature.
bool	audit_function_docs._return_tag_required (str return_type)
	Reports whether a Doxygen @return tag is required for a C symbol.
list[tuple[int, str, str]]	audit_function_docs._collect_c_signatures (Path path, str require_terminator)
	Collects C signatures from a header or source file.
list[AuditFinding]	audit_function_docs._audit_c_header (Path path)
	Audits public C declarations in one header file.
list[AuditFinding]	audit_function_docs._audit_c_source (Path path)
	Audits function definitions in one C source file.
list[str]	audit_function_docs._python_parameter_names (ast.FunctionDef|ast.AsyncFunctionDef node)
	Returns the meaningful Python parameter names for one function node.
bool	audit_function_docs._python_requires_return (ast.FunctionDef|ast.AsyncFunctionDef node)
	Reports whether one Python function should document a return value.
list[AuditFinding]	audit_function_docs._audit_python_file (Path path)
	Audits Python function docstrings in one file.
list[AuditFinding]	audit_function_docs._collect_findings ()
	Runs the full repository documentation audit.
None	audit_function_docs._print_findings (list[AuditFinding] findings)
	Prints findings in a grep-friendly format.
int	audit_function_docs.main ()
	Runs the repository function documentation audit from the command line.

Variables
	audit_function_docs.REPO_ROOT = Path(__file__).resolve().parents[1]
tuple	audit_function_docs.C_HEADER_DIRS = (REPO_ROOT / "include",)
tuple	audit_function_docs.C_SOURCE_DIRS = (REPO_ROOT / "src", REPO_ROOT / "tests" / "c")
tuple	audit_function_docs.PYTHON_DIRS = (REPO_ROOT / "scripts", REPO_ROOT / "tests")
tuple	audit_function_docs.PYTHON_EXTRA_FILES
	audit_function_docs.C_DECL_START_RE
	audit_function_docs.C_PARAM_RE = re.compile(r"@param(?:\[[^\]]+\])?\s+([A-Za-z_][A-Za-z0-9_]*)")

Detailed Description

Audits C and Python function documentation coverage across the repository.

This script enforces the repository's function-level documentation contract for:

• public C declarations in include/,
• C definitions in src/ and tests/c/,
• Python functions in scripts/, tests/, and Python-backed executable scripts.

It is intentionally lightweight. The C side uses signature scanning instead of a full parser, while the Python side uses ast.

Definition in file audit_function_docs.py.