Skip to content

Multiple sentences in multi-line docstring summary #283

@charlesbvll

Description

@charlesbvll

When reading PEP 257, I am under the impression that the one line summary at the beginning of the docstring should only be composed of a single sentence, from One-line Docstrings:

The docstring is a phrase ending in a period. It prescribes the function or method’s effect as a command (“Do this”, “Return that”), not as a description; e.g. don’t write “Returns the pathname …”.

From what I have tested, this seems correctly enforced in docformatter with single line docstrings. But shouldn't it also be enforce with multi-line docstrings? From Multi-line Docstrings:

Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description

From what I have tested:

def foo():
    """Do bar. This is the first sentence. And this is the second.

    And now this is the longer description.
    """

Is not reformatted by docformatter (1.75).

But:

def foo():
    """Do bar. This is the first sentence. And this is the second."""

gets (correctly) reformatted into:

def foo():
    """Do bar.

    This is the first sentence. And this is the second.
    """

Is this an inconsistency or am I wrong in my interpretation? Thanks!

Metadata

Metadata

Assignees

No one assigned

    Labels

    C: conventionRelates to docstring format conventionP: bugPEP 257 violation or existing functionality that doesn't work as documentedU: high

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions