`missing-docstring`¶

Part of: Presence Check


Check	presence
Category	required
Applies to	modules, classes, functions, methods
Since	v1.7.0

Public symbol has no docstring

What it detects¶

This rule flags public symbols — modules, classes, functions, and methods — that lack a docstring. Symbols filtered by ignore-init, ignore-magic, or ignore-private configuration are excluded from checking.

Why is this a problem?¶

Docstrings are the primary way both humans and AI agents understand what code does. A missing docstring means documentation generators (mkdocstrings, Sphinx) produce empty entries, and AI coding agents must infer purpose from implementation details alone — leading to lower-quality suggestions and higher error rates.

How to Fix¶

Add a docstring to the symbol. For functions, include a summary line and document parameters, return values, and exceptions:

def parse_config(path: str) -> dict:
    """Parse a TOML configuration file.

    Args:
        path: Path to the configuration file.

    Returns:
        Parsed configuration as a dictionary.

    Raises:
        FileNotFoundError: If the file does not exist.
    """

For classes, describe the purpose and list public attributes:

class UserProfile:
    """User profile with display preferences.

    Attributes:
        name (str): The user's display name.
        theme (str): Preferred color theme.
    """

For modules, add a module-level docstring at the top of the file:

"""Utility functions for configuration parsing."""

Example¶

ViolationFix

def parse_config(path: str) -> dict:
    with open(path) as f:
        return json.load(f)


class UserProfile:
    name: str
    email: str

def parse_config(path: str) -> dict:
    """Parse a JSON configuration file.

    Args:
        path: Path to the configuration file.

    Returns:
        Parsed configuration as a dictionary.

    Raises:
        FileNotFoundError: If the file does not exist.
    """
    with open(path) as f:
        return json.load(f)


class UserProfile:
    """User profile with contact information.

    Attributes:
        name (str): The user's display name.
        email (str): The user's email address.
    """

    name: str
    email: str

Suppression¶

To disable the presence check entirely, set enabled = false:

[tool.docvet.presence]
enabled = false

To exclude specific symbol types from checking, use the ignore flags:

[tool.docvet.presence]
ignore-init = true     # skip __init__ methods (default)
ignore-magic = true    # skip __repr__, __str__, etc. (default)
ignore-private = true  # skip _helper, _internal, etc. (default)

missing-docstring¶