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!
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
: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? FromMulti-line Docstrings
:From what I have tested:
Is not reformatted by
docformatter
(1.75
).But:
gets (correctly) reformatted into:
Is this an inconsistency or am I wrong in my interpretation? Thanks!