Feature: `overload-has-docstring` check

[Alberto-Codes]

Problem Statement

Per Python convention (and ruff D418), only the implementation function should have a docstring — @overload signatures exist purely for type checker consumption. Adding docstrings to overload signatures causes:

1. The overload bodies are never executed (they're ...)
2. Multiple docstrings for the same function confuse documentation generators
3. help(process) only shows the implementation's docstring
4. MkDocs/Sphinx may render duplicate or conflicting documentation

Current Behavior

@overload-decorated functions with docstrings produce no finding.

Proposed Solution

Detection

For each function/method with a docstring, check if it has an @overload decorator (from typing or typing_extensions). If so, emit a finding.

def _is_overload_decorated(node: ast.FunctionDef) -> bool:
    for decorator in node.decorator_list:
        if isinstance(decorator, ast.Name) and decorator.id == "overload":
            return True
        if isinstance(decorator, ast.Attribute) and decorator.attr == "overload":
            return True
    return False

Example

@overload
def fetch(url: str) -> str:
    """Fetch a URL as string."""  # overload-has-docstring ❌
    ...

@overload
def fetch(url: str, binary: Literal[True]) -> bytes:
    """Fetch a URL as bytes."""  # overload-has-docstring ❌
    ...

def fetch(url, binary=False):
    """Fetch a URL.

    Args:
        url: The URL to fetch.
        binary: If True, return bytes.

    Returns:
        str | bytes: The response content.
    """  # ✅ This is the correct place for the docstring
    ...

Configuration

[tool.docvet.presence]
check-overload-docstrings = true  # default

Could alternatively live in enrichment.py as a miscellaneous quality check. Placement is a design decision.

Acceptance Criteria

• @overload functions with docstrings produce a finding
• @typing.overload and @typing_extensions.overload both detected
• Implementation (non-overload) functions with docstrings are unaffected
• Config key check-overload-docstrings added

Technical Notes

Smallest issue in this batch. ~20 lines of code, ~30 lines of tests.

Category: recommended — best practice, not a hard requirement. Some projects intentionally document overloads for IDE tooltip purposes.

Ecosystem precedent: ruff D418 checks this. If a project uses docvet alongside or instead of ruff D-rules, this gap should be covered.

---

BMAD Workflow

When ready to implement:

• /bmad-bmm-quick-spec -> /bmad-bmm-quick-dev

[Alberto-Codes]

Shipped in #346 (commit 0d83358). Implementation lives in src/docvet/checks/presence.py — _check_overload_docstrings and _has_overload_decorator functions with check_overload_docstrings config toggle.