Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Multiple sentences in multi-line docstring summary #283

Open
charlesbvll opened this issue Jun 19, 2024 · 0 comments
Open

Multiple sentences in multi-line docstring summary #283

charlesbvll opened this issue Jun 19, 2024 · 0 comments
Labels
C: convention Relates to docstring format convention P: bug PEP 257 violation or existing functionality that doesn't work as documented U: high

Comments

@charlesbvll
Copy link

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!

@github-actions github-actions bot added the fresh This is a new issue label Jun 19, 2024
@weibullguy weibullguy added P: bug PEP 257 violation or existing functionality that doesn't work as documented C: convention Relates to docstring format convention and removed fresh This is a new issue labels Jul 31, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
C: convention Relates to docstring format convention P: bug PEP 257 violation or existing functionality that doesn't work as documented U: high
Projects
None yet
Development

No branches or pull requests

2 participants