Enrichment Check¶

The enrichment check implements Layer 3 (Completeness) of docvet's quality model. It uses AST analysis to detect missing docstring sections — Raises, Yields, Attributes, Examples, and more — by inspecting your code's actual behavior and structure. 21 rules cover functions, methods, classes, and modules across required, recommended, and scaffold categories.

docvet enrichment --all

Rules¶

Rule ID	Category	Applies To	Description
`missing-raises`	required	functions, methods	Function raises exceptions but has no `Raises:` section
`missing-returns`	required	functions, methods	Function returns a value but has no `Returns:` section
`missing-yields`	required	functions, methods	Generator yields but has no `Yields:` section
`missing-receives`	required	functions, methods	Generator uses `.send()` pattern but has no `Receives:` section
`missing-warns`	required	functions, methods	Function calls `warnings.warn()` but has no `Warns:` section
`missing-deprecation`	required	functions, methods	Function uses deprecation patterns but has no deprecation notice in docstring
`missing-param-in-docstring`	required	functions, methods	Signature parameter not documented in `Args:` section
`extra-param-in-docstring`	required	functions, methods	`Args:` section documents a parameter not in the function signature
`missing-other-parameters`	recommended	functions, methods	Function accepts `**kwargs` but has no `Other Parameters:` section
`missing-attributes`	required	classes, modules	Class or `__init__.py` module has undocumented attributes
`undocumented-init-params`	required	classes	Class `__init__` takes parameters but neither class nor `__init__` docstring has an `Args:` section
`missing-typed-attributes`	recommended	classes	`Attributes:` section entries lack typed format `name (type): description`
`missing-examples`	recommended	classes, modules	Symbol kind in `require-examples` list lacks `Examples:` section
`missing-cross-references`	recommended	modules	Module missing or malformed `See Also:` section
`extra-raises-in-docstring`	recommended	functions, methods	Docstring documents exceptions not raised in the function body
`extra-yields-in-docstring`	recommended	functions, methods	Docstring has a `Yields:` section but the function does not yield
`extra-returns-in-docstring`	recommended	functions, methods	Docstring has a `Returns:` section but the function does not return a value
`missing-return-type`	recommended	functions, methods	Returns section has no type and function has no return annotation
`trivial-docstring`	recommended	any symbol	Docstring summary line restates the symbol name without adding information
`prefer-fenced-code-blocks`	recommended	any symbol	`Examples:` section uses doctest `>>>` or rST `::` instead of fenced code blocks
`scaffold-incomplete`	scaffold	any symbol	Docstring contains unfilled `[TODO: ...]` placeholder markers from `docvet fix`

Required rules flag structural gaps where the docstring is objectively incomplete. Recommended rules flag best-practice improvements that enhance documentation quality. Scaffold findings flag placeholder content that must be filled in before merging.

Sphinx/RST mode

When docstring-style is set to "sphinx", section detection switches to RST field-list patterns and several rules are auto-disabled. See the configuration reference for details.

Best practice

Start with require-raises and missing-attributes — these catch the most impactful gaps. Disable require-other-parameters if your project doesn't use **kwargs heavily.

Example Output¶

src/myapp/utils.py:42: missing-raises Function 'parse_config' raises ValueError but has no Raises: section [required]
src/myapp/models.py:15: missing-attributes Dataclass 'UserProfile' has no Attributes: section [required]
src/myapp/generators.py:28: missing-yields Function 'stream_results' yields but has no Yields: section [required]
src/myapp/api.py:73: missing-other-parameters Function 'create_client' accepts **kwargs but has no Other Parameters: section [recommended]

4 findings (3 required, 1 recommended)

Configuration¶

The enrichment check is configured under [tool.docvet.enrichment] in your pyproject.toml. Each rule has a boolean toggle (except require-examples which takes a list).

Key	Type	Default	Description
`require-raises`	`bool`	`true`	Require `Raises:` sections when exceptions are raised
`require-returns`	`bool`	`true`	Require `Returns:` sections when functions return a value
`require-yields`	`bool`	`true`	Require `Yields:` sections in generators
`require-receives`	`bool`	`true`	Require `Receives:` sections for `.send()` generators
`require-warns`	`bool`	`true`	Require `Warns:` sections when `warnings.warn()` is called
`require-other-parameters`	`bool`	`true`	Require `Other Parameters:` for `**kwargs`
`require-attributes`	`bool`	`true`	Require `Attributes:` sections on classes and modules
`require-typed-attributes`	`bool`	`true`	Require typed format in `Attributes:` entries
`require-cross-references`	`bool`	`true`	Require `See Also:` in module docstrings
`prefer-fenced-code-blocks`	`bool`	`true`	Prefer fenced code blocks over doctest `>>>` format
`require-param-agreement`	`bool`	`true`	Require parameter agreement between function signatures and `Args:` sections
`require-deprecation-notice`	`bool`	`true`	Require deprecation notice when function uses deprecation patterns
`exclude-args-kwargs`	`bool`	`true`	Exclude `args` and `*kwargs` from parameter agreement checks
`check-trivial-docstrings`	`bool`	`true`	Flag docstrings whose summary line trivially restates the symbol name
`require-return-type`	`bool`	`false`	Require return type via typed `Returns:` entry or `->` annotation (opt-in)
`require-init-params`	`bool`	`false`	Require `Args:` section when `__init__` takes parameters (opt-in)
`check-extra-raises`	`bool`	`false`	Flag documented exceptions not raised in function body (opt-in due to propagated exception false positives)
`check-extra-yields`	`bool`	`true`	Flag `Yields:` section when function has no `yield` statement
`check-extra-returns`	`bool`	`true`	Flag `Returns:` section when function has no meaningful return
`require-examples`	`list[str]`	`["class", "protocol", "dataclass", "enum"]`	Symbol kinds requiring `Examples:` sections
`scaffold-incomplete`	`bool`	`true`	Detect unfilled `[TODO: ...]` placeholder markers left by `docvet fix`

Example configuration to disable specific rules:

[tool.docvet.enrichment]
require-warns = false
require-other-parameters = false
require-examples = ["class", "dataclass"]

Usage¶

Run the enrichment check on your entire codebase:

docvet enrichment --all

Check only files with unstaged changes (default):

docvet enrichment

Check only staged files (useful in pre-commit hooks):

docvet enrichment --staged

Check specific files:

docvet enrichment --files src/myapp/utils.py --files src/myapp/models.py

Add --verbose for file count and timing, or -q to suppress the summary line:

docvet enrichment --all --verbose
docvet enrichment --all -q

Or run enrichment as part of all checks:

docvet check --all