Function parse_docstring

python/scripts/generate-docs.py:167–241

Parse docstring into components.

(docstring: str | None)

def parse_docstring(docstring: str | None) -> dict[str, Any]:
    """Parse docstring into components."""
    if not docstring:
        return {
            "description": "",
            "params": {},
            "returns": None,
            "examples": [],
            "deprecated": None,
        }

    lines = docstring.strip().split("\n")
    description_lines = []
    params: dict[str, str] = {}
    returns = None
    examples: list[str] = []
    deprecated_lines: list[str] = []

    section = "description"
    current_param = None
    example_lines: list[str] = []

    for line in lines:
        stripped = line.strip()

        # Check for a ``.. deprecated::`` directive (reStructuredText).
        if re.match(r"\.\.\s+deprecated::", stripped):
            section = "deprecated"
            rest = re.sub(r"\.\.\s+deprecated::\s*", "", stripped).strip()
            if rest:
                deprecated_lines.append(rest)
            continue

        # Check for :param name: description
        param_match = re.match(r":param\s+(\w+):\s*(.*)", stripped)
        if param_match:
            section = "params"
            current_param = param_match.group(1)
            params[current_param] = param_match.group(2)
            continue

        # Check for :returns: or :return:
        return_match = re.match(r":returns?:\s*(.*)", stripped)
        if return_match:
            section = "returns"
            returns = return_match.group(1)
            continue

        # Check for Example section
        if stripped.lower().startswith("example"):
            section = "examples"
            continue

        # Add to appropriate section
        if section == "description":
            description_lines.append(stripped)
        elif section == "params" and current_param and stripped:
            params[current_param] += " " + stripped