Skip to content
My Code, My RulesMy Code, My Rules

PY-DOCU0001 · compact_house_docstring

Enforce compact self-contained house docstrings where documentation exists.

This is a deterministic rule for python. Read its implementation.

Definition

Section titled “Definition”

For every docstring a method or a function states, require a nonempty punctuated one-line summary within maximum_summary. Reject summaries that only send the reader elsewhere, Google or NumPy Args and Returns headings, and reStructuredText field lists. Accept compact name: description lines and require their description to be nonempty. Missing callable docstrings are left to dedicated coverage tools, and a module docstring belongs to the module family rather than to this one.

Evidence

Section titled “Evidence”

Each finding points at the callable that owns the docstring and names which of the two shapes broke, the summary line or the body beneath it, beside how long the summary runs against what this project accepts. More than one violation in the same docstring stays a separate finding. The repair is a choice, since only the author knows what the sentence was trying to say.

Exceptions

Section titled “Exceptions”

A docstring may contain technical reStructuredText sections, examples, directives, URLs, and references after its self-contained summary. Attribute documentation and ordinary multiline string values are not docstrings. Externally required doc formats can disable the rule at that adapter boundary.

Examples

Section titled “Examples”

Bad

Section titled “Bad”
def encode(text: str) -> list[int]:
    '''See the tokenizer documentation.


    Args:
        text: Input text.
    Returns:
        Token IDs.
    '''

Good

Section titled “Good”
def encode(text: str) -> list[int]:
    '''Encode text to token IDs.


    text: Input string to tokenize.
    '''

References

Section titled “References”