audit_function_docs Namespace Reference

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

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

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

Function Documentation

_iter_c_files()

list[Path] audit_function_docs._iter_c_files ( tuple[Path, ...]  directories )

protected

Returns all C or header files below the configured directories.

Parameters

[in]

directories

Root directories to scan.

Returns

Sorted list of matching file paths.

Definition at line 63 of file audit_function_docs.py.

def _iter_c_files(directories: tuple[Path, ...]) -> list[Path]:
    """!
    @brief Returns all C or header files below the configured directories.
    @param[in] directories Root directories to scan.
    @return Sorted list of matching file paths.
    """
 
    files: list[Path] = []
    for directory in directories:
        if not directory.exists():
            continue
        files.extend(sorted(path for path in directory.rglob("*") if path.suffix in {".c", ".h"}))
    return sorted(files)
 
 

Here is the caller graph for this function:

_iter_python_files()

list[Path] audit_function_docs._iter_python_files ( )

protected

Returns all Python source files covered by the audit.

Returns

Sorted list of Python-backed source files.

Definition at line 78 of file audit_function_docs.py.

def _iter_python_files() -> list[Path]:
    """!
    @brief Returns all Python source files covered by the audit.
    @return Sorted list of Python-backed source files.
    """
 
    files: set[Path] = set()
    for directory in PYTHON_DIRS:
        if not directory.exists():
            continue
        files.update(path for path in directory.rglob("*.py"))
 
    for path in PYTHON_EXTRA_FILES:
        if path.exists():
            files.add(path)
 
    return sorted(files)
 
 

Here is the caller graph for this function:

_read_lines()

list[str] audit_function_docs._read_lines ( Path  path )

protected

Reads a text file into a list of lines.

Parameters

[in]

path

Path to read.

Returns

File contents split into lines without trailing newline markers.

Definition at line 97 of file audit_function_docs.py.

def _read_lines(path: Path) -> list[str]:
    """!
    @brief Reads a text file into a list of lines.
    @param[in] path Path to read.
    @return File contents split into lines without trailing newline markers.
    """
 
    return path.read_text(encoding="utf-8", errors="ignore").splitlines()
 
 

Here is the caller graph for this function:

_relative_path()

str audit_function_docs._relative_path ( Path  path )

protected

Returns a repository-relative path string.

Parameters

[in]

path

Absolute or repository-local path.

Returns

POSIX-style repository-relative path.

Definition at line 107 of file audit_function_docs.py.

def _relative_path(path: Path) -> str:
    """!
    @brief Returns a repository-relative path string.
    @param[in] path Absolute or repository-local path.
    @return POSIX-style repository-relative path.
    """
 
    return path.relative_to(REPO_ROOT).as_posix()
 
 

Here is the caller graph for this function:

_find_attached_doxygen_block()

tuple[int, int] | None audit_function_docs._find_attached_doxygen_block ( list[str]  lines, int  start_line  )

protected

Finds the Doxygen block immediately attached to a declaration or definition.

Parameters

[in]	lines	File content lines.
[in]	start_line	0-based line index where the symbol begins.

Returns

(start, end) line indices for the attached block, or None.

Definition at line 117 of file audit_function_docs.py.

def _find_attached_doxygen_block(lines: list[str], start_line: int) -> tuple[int, int] | None:
    """!
    @brief Finds the Doxygen block immediately attached to a declaration or definition.
    @param[in] lines File content lines.
    @param[in] start_line 0-based line index where the symbol begins.
    @return `(start, end)` line indices for the attached block, or `None`.
    """
 
    probe = start_line - 1
    while probe >= 0 and lines[probe].strip() == "":
        probe -= 1
 
    if probe < 0 or "*/" not in lines[probe]:
        return None
 
    end = probe
    while probe >= 0 and "/**" not in lines[probe]:
        probe -= 1
 
    if probe < 0:
        return None
 
    return probe, end
 
 

Here is the caller graph for this function:

_split_c_parameters()

list[str] audit_function_docs._split_c_parameters ( str  signature )

protected

Splits a C signature parameter list into parameter names.

Parameters

[in]

signature

Full function signature text.

Returns

Ordered list of parameter names excluding void and variadics.

Definition at line 142 of file audit_function_docs.py.

def _split_c_parameters(signature: str) -> list[str]:
    """!
    @brief Splits a C signature parameter list into parameter names.
    @param[in] signature Full function signature text.
    @return Ordered list of parameter names excluding `void` and variadics.
    """
 
    start = signature.find("(")
    end = signature.rfind(")")
    if start < 0 or end < 0 or end <= start:
        return []
 
    raw = signature[start + 1:end]
    params: list[str] = []
    depth = 0
    current: list[str] = []
    for char in raw:
        if char == "," and depth == 0:
            params.append("".join(current).strip())
            current = []
            continue
        current.append(char)
        if char in "([{":
            depth += 1
        elif char in ")]}":
            depth -= 1
    if current:
        params.append("".join(current).strip())
 
    names: list[str] = []
    for param in params:
        if not param or param == "void" or param == "...":
            continue
 
        clean = re.sub(r"\b(const|volatile|restrict|extern|static|register|inline)\b", "", param)
        clean = clean.strip()
        match = re.search(r"([A-Za-z_][A-Za-z0-9_]*)\s*(?:\[[^\]]*\]\s*)*$", clean)
        if match:
            names.append(match.group(1))
 
    return names
 
 

Here is the caller graph for this function:

_c_return_type()

str audit_function_docs._c_return_type ( str  signature, str  symbol  )

protected

Extracts the declared C return type prefix for one signature.

Parameters

[in]	signature	Full function signature text.
[in]	symbol	Function name contained in the signature.

Returns

Normalized return-type prefix.

Definition at line 185 of file audit_function_docs.py.

def _c_return_type(signature: str, symbol: str) -> str:
    """!
    @brief Extracts the declared C return type prefix for one signature.
    @param[in] signature Full function signature text.
    @param[in] symbol Function name contained in the signature.
    @return Normalized return-type prefix.
    """
 
    prefix = signature.split(symbol, 1)[0]
    return " ".join(prefix.split())
 
 

Here is the caller graph for this function:

_return_tag_required()

bool audit_function_docs._return_tag_required ( str  return_type )

protected

Reports whether a Doxygen @return tag is required for a C symbol.

Parameters

[in]

return_type

Normalized return-type prefix.

Returns

True when the symbol does not return void.

Definition at line 197 of file audit_function_docs.py.

def _return_tag_required(return_type: str) -> bool:
    """!
    @brief Reports whether a Doxygen `@return` tag is required for a C symbol.
    @param[in] return_type Normalized return-type prefix.
    @return `True` when the symbol does not return `void`.
    """
 
    stripped = return_type.replace("extern ", "").replace("static ", "").replace("inline ", "").strip()
    return not stripped.startswith("void")
 
 

Here is the caller graph for this function:

_collect_c_signatures()

list[tuple[int, str, str]] audit_function_docs._collect_c_signatures ( Path  path, str  require_terminator  )

protected

Collects C signatures from a header or source file.

Parameters

[in]	path	File to scan.
[in]	require_terminator	Expected signature terminator, either ; or {.

Returns

List of (start_line, symbol, signature_text) tuples.

Definition at line 208 of file audit_function_docs.py.

def _collect_c_signatures(path: Path, require_terminator: str) -> list[tuple[int, str, str]]:
    """!
    @brief Collects C signatures from a header or source file.
    @param[in] path File to scan.
    @param[in] require_terminator Expected signature terminator, either `;` or `{`.
    @return List of `(start_line, symbol, signature_text)` tuples.
    """
 
    lines = _read_lines(path)
    signatures: list[tuple[int, str, str]] = []
    line_index = 0
    in_block_comment = False
 
    while line_index < len(lines):
        stripped = lines[line_index].lstrip()
        if in_block_comment:
            if "*/" in lines[line_index]:
                in_block_comment = False
            line_index += 1
            continue
 
        if "/*" in lines[line_index]:
            if "*/" not in lines[line_index]:
                in_block_comment = True
            line_index += 1
            continue
 
        if stripped.startswith(("#", "/*", "*", "//")) or "(" not in lines[line_index]:
            line_index += 1
            continue
 
        match = C_DECL_START_RE.match(lines[line_index])
        if not match:
            line_index += 1
            continue
 
        symbol = match.group(1)
        start_line = line_index
        signature = lines[line_index].rstrip()
        while line_index + 1 < len(lines) and require_terminator not in signature and ";" not in signature:
            line_index += 1
            signature += " " + lines[line_index].strip()
 
        if require_terminator == ";" and ";" in signature:
            signatures.append((start_line, symbol, signature))
        elif require_terminator == "{" and "{" in signature and ";" not in signature.split("{", 1)[0]:
            signatures.append((start_line, symbol, signature))
 
        line_index += 1
 
    return signatures
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_audit_c_header()

list[AuditFinding] audit_function_docs._audit_c_header ( Path  path )

protected

Audits public C declarations in one header file.

Parameters

[in]

path

Header file to scan.

Returns

Findings emitted for the header.

Definition at line 261 of file audit_function_docs.py.

def _audit_c_header(path: Path) -> list[AuditFinding]:
    """!
    @brief Audits public C declarations in one header file.
    @param[in] path Header file to scan.
    @return Findings emitted for the header.
    """
 
    findings: list[AuditFinding] = []
    lines = _read_lines(path)
    for start_line, symbol, signature in _collect_c_signatures(path, ";"):
        block_range = _find_attached_doxygen_block(lines, start_line)
        if block_range is None:
            findings.append(AuditFinding(_relative_path(path), start_line + 1, symbol, "missing attached Doxygen block"))
            continue
 
        block = "\n".join(lines[block_range[0]:block_range[1] + 1])
        if "@brief" not in block:
            findings.append(AuditFinding(_relative_path(path), start_line + 1, symbol, "missing @brief tag"))
 
        declared_params = _split_c_parameters(signature)
        documented_params = set(C_PARAM_RE.findall(block))
        if set(declared_params) != documented_params:
            findings.append(
                AuditFinding(
                    _relative_path(path),
                    start_line + 1,
                    symbol,
                    f"documented @param names {sorted(documented_params)} do not match declaration {declared_params}",
                )
            )
 
        if _return_tag_required(_c_return_type(signature, symbol)) and "@return" not in block:
            findings.append(AuditFinding(_relative_path(path), start_line + 1, symbol, "missing @return tag"))
 
    return findings
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_audit_c_source()

list[AuditFinding] audit_function_docs._audit_c_source ( Path  path )

protected

Audits function definitions in one C source file.

Parameters

[in]

path

Source file to scan.

Returns

Findings emitted for the source file.

Definition at line 298 of file audit_function_docs.py.

def _audit_c_source(path: Path) -> list[AuditFinding]:
    """!
    @brief Audits function definitions in one C source file.
    @param[in] path Source file to scan.
    @return Findings emitted for the source file.
    """
 
    findings: list[AuditFinding] = []
    lines = _read_lines(path)
    for start_line, symbol, _signature in _collect_c_signatures(path, "{"):
        block_range = _find_attached_doxygen_block(lines, start_line)
        if block_range is None:
            findings.append(AuditFinding(_relative_path(path), start_line + 1, symbol, "missing attached Doxygen block"))
            continue
 
        block = "\n".join(lines[block_range[0]:block_range[1] + 1])
        if "@brief" not in block:
            findings.append(AuditFinding(_relative_path(path), start_line + 1, symbol, "missing @brief tag"))
 
    return findings
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_python_parameter_names()

list[str] audit_function_docs._python_parameter_names ( ast.FunctionDef | ast.AsyncFunctionDef  node )

protected

Returns the meaningful Python parameter names for one function node.

Parameters

[in]

node

Function AST node.

Returns

Ordered list of parameters expected in @param tags.

Definition at line 320 of file audit_function_docs.py.

def _python_parameter_names(node: ast.FunctionDef | ast.AsyncFunctionDef) -> list[str]:
    """!
    @brief Returns the meaningful Python parameter names for one function node.
    @param[in] node Function AST node.
    @return Ordered list of parameters expected in `@param` tags.
    """
 
    names = [arg.arg for arg in node.args.posonlyargs + node.args.args + node.args.kwonlyargs]
    names = [name for name in names if name not in {"self", "cls"}]
    if node.args.vararg is not None:
        names.append(node.args.vararg.arg)
    if node.args.kwarg is not None:
        names.append(node.args.kwarg.arg)
    return names
 
 

Here is the caller graph for this function:

_python_requires_return()

bool audit_function_docs._python_requires_return ( ast.FunctionDef | ast.AsyncFunctionDef  node )

protected

Reports whether one Python function should document a return value.

Parameters

[in]

node

Function AST node.

Returns

True when the function returns a non-None value.

Definition at line 336 of file audit_function_docs.py.

def _python_requires_return(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
    """!
    @brief Reports whether one Python function should document a return value.
    @param[in] node Function AST node.
    @return `True` when the function returns a non-`None` value.
    """
 
    for child in ast.walk(node):
        if isinstance(child, ast.Return) and child.value is not None:
            if isinstance(child.value, ast.Constant) and child.value.value is None:
                continue
            return True
    return False
 
 

Here is the caller graph for this function:

_audit_python_file()

list[AuditFinding] audit_function_docs._audit_python_file ( Path  path )

protected

Audits Python function docstrings in one file.

Parameters

[in]

path

Python source file to scan.

Returns

Findings emitted for the Python file.

Definition at line 351 of file audit_function_docs.py.

def _audit_python_file(path: Path) -> list[AuditFinding]:
    """!
    @brief Audits Python function docstrings in one file.
    @param[in] path Python source file to scan.
    @return Findings emitted for the Python file.
    """
 
    findings: list[AuditFinding] = []
    source = path.read_text(encoding="utf-8")
    tree = ast.parse(source, filename=str(path))
 
    for node in ast.walk(tree):
        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
            continue
 
        docstring = ast.get_docstring(node)
        if docstring is None:
            findings.append(AuditFinding(_relative_path(path), node.lineno, node.name, "missing Python docstring"))
            continue
 
        if "@brief" not in docstring:
            findings.append(AuditFinding(_relative_path(path), node.lineno, node.name, "missing @brief tag"))
 
        declared_params = _python_parameter_names(node)
        documented_params = set(re.findall(r"@param(?:\[[^\]]+\])?\s+([A-Za-z_][A-Za-z0-9_]*)", docstring))
        if set(declared_params) != documented_params:
            findings.append(
                AuditFinding(
                    _relative_path(path),
                    node.lineno,
                    node.name,
                    f"documented @param names {sorted(documented_params)} do not match declaration {declared_params}",
                )
            )
 
        if _python_requires_return(node) and "@return" not in docstring:
            findings.append(AuditFinding(_relative_path(path), node.lineno, node.name, "missing @return tag"))
 
    return findings
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_collect_findings()

list[AuditFinding] audit_function_docs._collect_findings ( )

protected

Runs the full repository documentation audit.

Returns

Sorted list of all findings emitted by the audit.

Definition at line 392 of file audit_function_docs.py.

def _collect_findings() -> list[AuditFinding]:
    """!
    @brief Runs the full repository documentation audit.
    @return Sorted list of all findings emitted by the audit.
    """
 
    findings: list[AuditFinding] = []
    for path in _iter_c_files(C_HEADER_DIRS):
        findings.extend(_audit_c_header(path))
    for path in _iter_c_files(C_SOURCE_DIRS):
        if path.suffix == ".c":
            findings.extend(_audit_c_source(path))
    for path in _iter_python_files():
        findings.extend(_audit_python_file(path))
 
    return sorted(findings, key=lambda item: (item.path, item.line, item.symbol, item.message))
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_print_findings()

None audit_function_docs._print_findings ( list[AuditFinding]  findings )

protected

Prints findings in a grep-friendly format.

Parameters

[in]

findings

Findings to render.

Definition at line 410 of file audit_function_docs.py.

def _print_findings(findings: list[AuditFinding]) -> None:
    """!
    @brief Prints findings in a grep-friendly format.
    @param[in] findings Findings to render.
    """
 
    for finding in findings:
        print(f"{finding.path}:{finding.line}: {finding.symbol}: {finding.message}")
 
 

Here is the caller graph for this function:

main()

int audit_function_docs.main

(

)

Runs the repository function documentation audit from the command line.

Returns

Process exit status.

Definition at line 420 of file audit_function_docs.py.

def main() -> int:
    """!
    @brief Runs the repository function documentation audit from the command line.
    @return Process exit status.
    """
 
    findings = _collect_findings()
    if findings:
        _print_findings(findings)
        print(f"\nFound {len(findings)} documentation issue(s).", file=sys.stderr)
        return 1
 
    print("Function documentation audit passed.")
    return 0
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

REPO_ROOT

audit_function_docs.REPO_ROOT = Path(__file__).resolve().parents[2]

Definition at line 25 of file audit_function_docs.py.

C_HEADER_DIRS

tuple audit_function_docs.C_HEADER_DIRS = (REPO_ROOT / "include",)

Definition at line 27 of file audit_function_docs.py.

C_SOURCE_DIRS

tuple audit_function_docs.C_SOURCE_DIRS = (REPO_ROOT / "src", REPO_ROOT / "tests" / "c")

Definition at line 28 of file audit_function_docs.py.

PYTHON_DIRS

tuple audit_function_docs.PYTHON_DIRS = (REPO_ROOT / "picurv_cli", REPO_ROOT / "tests")

Definition at line 29 of file audit_function_docs.py.

PYTHON_EXTRA_FILES

tuple audit_function_docs.PYTHON_EXTRA_FILES

Initial value:

=  (
    REPO_ROOT / "picurv_cli" / "picurv",
    REPO_ROOT / "generators" / "grid.gen",
    REPO_ROOT / "generators" / "profile.gen",
    REPO_ROOT / "generators" / "ic.gen",
    REPO_ROOT / "generators" / "plot.gen",
)

Definition at line 30 of file audit_function_docs.py.

C_DECL_START_RE

audit_function_docs.C_DECL_START_RE

Initial value:

=  re.compile(
    r"^\s*(?!typedef\b)(?!if\b)(?!for\b)(?!while\b)(?!switch\b)(?!return\b)(?!else\b)"
    r"(?:extern\s+)?(?:static\s+)?(?:inline\s+)?(?:const\s+)?(?:unsigned\s+|signed\s+)?"
    r"(?:[A-Za-z_][A-Za-z0-9_]*\s+)+(?:\*\s*)*"
    r"([A-Za-z_][A-Za-z0-9_]*)\s*\‍("
)

Definition at line 38 of file audit_function_docs.py.

C_PARAM_RE

audit_function_docs.C_PARAM_RE = re.compile(r"@param(?:\[[^\]]+\])?\s+([A-Za-z_][A-Za-z0-9_]*)")

Definition at line 44 of file audit_function_docs.py.