Skip to content

missing-public-function-documentation (PDF608)

Added in 1.0.0 Never fix By default

Part of the PDF rule category.

View source · View documentation source · Search issues

Fix is not available.

What it does

Checks for public top-level functions that are missing docstrings.

Methods are handled by the method rules, and local functions inside functions are ignored. A top-level function is public when its own name and containing module path are public.

Why is this useful?

Public functions should describe their behavior and API contract.

Ruff compatibility

This rule replaces Ruff's D103.

Examples

A public top-level function without a docstring is reported:

def connect():
    pass

PDF608: Line 1: Public function 'connect' is missing docstring

Async top-level functions are checked the same way:

async def connect():
    pass

PDF608: Line 1: Public function 'connect' is missing docstring

A documented public top-level function is accepted:

def connect():
    """Connect to the service."""

Methods and local functions are not top-level function targets:

class Client:
    """Client."""

    def connect(self):
        pass

def build():
    """Build a client."""

    def inner():
        pass

Private function names and private module paths are handled by PDF609 instead:

def connect():
    pass

def _connect():
    pass

Options