audit_function_docs Namespace Reference

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

Functions
bool	_has_specific_description (str comment)
	Report whether a function comment contains a non-stub description.
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_comment_block (list[str] lines, int start_line, bool require_doxygen)
	Finds the documentation 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, set[str] public_symbols)
	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
tuple	PYTHON_EXTRA_FILES
	C_DECL_START_RE
	C_PARAM_RE = re.compile(r"@param(?:\[[^\]]+\])?\s+([A-Za-z_][A-Za-z0-9_]*)")
	GENERIC_DESCRIPTION_RE
	STUB_IMPLEMENTATION_RE
	GENERIC_PUBLIC_PARAM_RE

Function Documentation

_has_specific_description()

bool audit_function_docs._has_specific_description ( str  comment )

protected

Report whether a function comment contains a non-stub description.

Parameters

[in]

comment

Attached C comment or Python docstring to examine.

Returns

True when the description is not a known placeholder or label.

The audit deliberately uses conservative, transparent heuristics instead of attempting to judge prose. It rejects descriptions that only classify a symbol (for example, "helper function") and comments with no prose beyond Doxygen tags. Reviewers remain responsible for domain correctness.

Definition at line 67 of file audit_function_docs.py.

def _has_specific_description(comment: str) -> bool:
    """!
    @brief Report whether a function comment contains a non-stub description.
    @param[in] comment Attached C comment or Python docstring to examine.
    @return `True` when the description is not a known placeholder or label.
 
    The audit deliberately uses conservative, transparent heuristics instead of
    attempting to judge prose.  It rejects descriptions that only classify a
    symbol (for example, "helper function") and comments with no prose beyond
    Doxygen tags.  Reviewers remain responsible for domain correctness.
    """
 
    brief = re.search(r"@brief\s+([^\n*]+)", comment, re.IGNORECASE)
    prose = brief.group(1) if brief else comment
    prose = re.sub(r"@(?:param|return|file|details|note|warning)\b[^\n]*", "", prose)
    prose = re.sub(r"[/!*`#]", " ", prose)
    words = re.findall(r"[A-Za-z][A-Za-z0-9_-]*", prose)
    if len(words) < 3:
        return False
    normalized = prose.strip()
    return (
        GENERIC_DESCRIPTION_RE.fullmatch(normalized) is None
        and STUB_IMPLEMENTATION_RE.match(normalized) is None
    )
 
 
@dataclass(frozen=True)

Here is the caller graph for this function:

_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 109 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 124 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 143 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 153 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_comment_block()

tuple[int, int] | None audit_function_docs._find_attached_comment_block ( list[str]  lines, int  start_line, bool  require_doxygen  )

protected

Finds the documentation 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.
[in]	require_doxygen	Require a Doxygen /** block instead of allowing a regular /* implementation comment.

Returns

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

Definition at line 163 of file audit_function_docs.py.

                                 require_doxygen: bool) -> tuple[int, int] | None:
    """!
    @brief Finds the documentation 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.
    @param[in] require_doxygen Require a Doxygen `/**` block instead of allowing a
                               regular `/*` implementation comment.
    @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]:
        if probe >= 0 and not require_doxygen and lines[probe].lstrip().startswith("//"):
            end = probe
            while probe >= 0 and lines[probe].lstrip().startswith("//"):
                probe -= 1
            return probe + 1, end
        return None
 
    end = probe
    marker = "/**" if require_doxygen else "/*"
    while probe >= 0 and marker 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 197 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 240 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 252 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 263 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 316 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_comment_block(lines, start_line, require_doxygen=True)
        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"))
        elif not _has_specific_description(block):
            findings.append(
                AuditFinding(
                    _relative_path(path), start_line + 1, symbol,
                    "stub @brief; describe the function's result, state change, or numerical role",
                )
            )
        if GENERIC_PUBLIC_PARAM_RE.search(block):
            findings.append(
                AuditFinding(
                    _relative_path(path), start_line + 1, symbol,
                    "generic @param; describe the input, output, ownership, or numerical meaning",
                )
            )
 
        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, set[str]  public_symbols  )

protected

Audits function definitions in one C source file.

Parameters

[in]	path	Source file to scan.
[in]	public_symbols	Symbols with canonical public-header documentation.

Returns

Findings emitted for the source file.

Definition at line 367 of file audit_function_docs.py.

def _audit_c_source(path: Path, public_symbols: set[str]) -> list[AuditFinding]:
    """!
    @brief Audits function definitions in one C source file.
    @param[in] path Source file to scan.
    @param[in] public_symbols Symbols with canonical public-header documentation.
    @return Findings emitted for the source file.
    """
 
    findings: list[AuditFinding] = []
    lines = _read_lines(path)
    for start_line, symbol, _signature in _collect_c_signatures(path, "{"):
        # Public declarations own the rendered API contract. Allow regular
        # implementation comments here so Doxygen does not merge a second,
        # partial parameter list from the definition and emit false warnings.
        block_range = _find_attached_comment_block(lines, start_line, require_doxygen=False)
        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])
        # A public declaration's Doxygen block is the canonical user-facing
        # description.  Definitions of private helpers have no such contract,
        # so their attached implementation comment must stand on its own.
        if symbol not in public_symbols and not _has_specific_description(block):
            findings.append(
                AuditFinding(
                    _relative_path(path), start_line + 1, symbol,
                    "stub implementation comment; explain the function's computation or state change",
                )
            )
 
    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 401 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 417 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 432 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"))
        elif not _has_specific_description(docstring):
            findings.append(
                AuditFinding(
                    _relative_path(path), node.lineno, node.name,
                    "stub @brief; explain the function's result, state change, or validation role",
                )
            )
 
        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 480 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] = []
    header_files = _iter_c_files(C_HEADER_DIRS)
    public_symbols = {
        symbol
        for path in header_files
        for _line, symbol, _signature in _collect_c_signatures(path, ";")
    }
    for path in header_files:
        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, public_symbols))
    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 504 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 514 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 27 of file audit_function_docs.py.

C_HEADER_DIRS

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

Definition at line 29 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 30 of file audit_function_docs.py.

PYTHON_DIRS

tuple audit_function_docs.PYTHON_DIRS

Initial value:

=  (
    REPO_ROOT / "picurv_cli",
    REPO_ROOT / "generators",
    REPO_ROOT / "tests",
)

Definition at line 31 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 36 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 44 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 50 of file audit_function_docs.py.

GENERIC_DESCRIPTION_RE

audit_function_docs.GENERIC_DESCRIPTION_RE

Initial value:

=  re.compile(
    r"(?:a |an |the )?(?:public interface|helper function|implementation of|internal helper|"
    r"routine|function|test helper|utility function|helper routine)\.?$",
    re.IGNORECASE,
)

Definition at line 51 of file audit_function_docs.py.

STUB_IMPLEMENTATION_RE

audit_function_docs.STUB_IMPLEMENTATION_RE

Initial value:

=  re.compile(
    r"(?:internal )?helper implementation\s*:", re.IGNORECASE
)

Definition at line 56 of file audit_function_docs.py.

GENERIC_PUBLIC_PARAM_RE

audit_function_docs.GENERIC_PUBLIC_PARAM_RE

Initial value:

=  re.compile(
    r"@param(?:\[[^\]]+\])?\s+[A-Za-z_][A-Za-z0-9_]*\s+"
    r"(?:parameter|argument)\b.*\bpassed to\b|"
    r"@param(?:\[[^\]]+\])?\s+[A-Za-z_][A-Za-z0-9_]*\s+(?:output:|the)\s*$",
    re.IGNORECASE | re.MULTILINE,
)

Definition at line 59 of file audit_function_docs.py.