docstrings

Functions:

• validate_docstring –

validate_docstring

validate_docstring(raw: str) -> dict[str, Any]

Source code in src/arx/docstrings.py

def validate_docstring(raw: str) -> dict[str, Any]:
    """
    title: Validate docstring content as Douki YAML.
    parameters:
      raw:
        type: str
        description: Raw text found inside the docstring block.
    returns:
      type: dict[str, Any]
    """
    normalized = textwrap.dedent(raw).strip()
    if not normalized:
        raise ValueError("Docstring block cannot be empty.")

    try:
        data = yaml.safe_load(normalized)
    except yaml.YAMLError as err:
        raise ValueError("Docstring content must be valid YAML.") from err

    if not isinstance(data, dict):
        raise ValueError("Docstring YAML must define an object mapping.")

    try:
        validate(instance=data, schema=_schema())
    except ValidationError as err:
        raise ValueError(
            f"Docstring YAML does not follow douki schema: {err.message}"
        ) from err

    return cast(dict[str, Any], data)