PyCQA / docformatter

Formats docstrings to follow PEP 257
https://pypi.python.org/pypi/docformatter
MIT License
530 stars 61 forks source link

Multiple sentences in multi-line docstring summary #283

Open charlesbvll opened 3 months ago

charlesbvll commented 3 months ago

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!