Skip to content

missing-param-in-docstring

Part of: Enrichment Check
Check enrichment
Category required
Applies to functions, methods
Since v1.14.0

Signature parameter not documented in Args section

What it detects

This rule flags functions and methods that have an Args: section in their docstring but omit one or more parameters from the function signature. Parameters documented with * or ** prefixes (e.g., *args, **kwargs) are matched by bare name.

Why is this a problem?

When signature parameters are missing from the Args: section, callers don't know what values to pass or what each parameter does. API documentation generated by mkdocstrings will show the parameter in the signature but provide no description, creating a confusing gap.

How to Fix

Add the missing parameter to the Args: section with a description:

Args:
    host: The server hostname.
    port: The server port number.
    timeout: Connection timeout in seconds. Defaults to 30.0.

Example

def connect(host: str, port: int, timeout: float = 30.0):
    """Connect to a server.

    Args:
        host: The server hostname.
    """

def connect(host: str, port: int, timeout: float = 30.0):
    """Connect to a server.

    Args:
        host: The server hostname.
        port: The server port number.
        timeout: Connection timeout in seconds. Defaults to 30.0.
    """

Configuration

By default, *args and **kwargs are excluded from agreement checks — undocumented star arguments are not flagged. Set exclude-args-kwargs = false to require their documentation (matches pydoclint's default behavior where --should-document-star-arguments = true).

[tool.docvet.enrichment]
exclude-args-kwargs = false

To disable this rule entirely:

[tool.docvet.enrichment]
require-param-agreement = false

Exceptions

This rule is automatically skipped when:

  • The docstring has no Args: section (a separate concern)
  • The symbol is a class, module, or other non-function type