Details
-
Type:
RFC
-
Status: Implemented
-
Resolution: Done
-
Component/s: DM
-
Labels:None
Description
The Developer Guide, under "Documenting Python APIs with docstrings", currently says:
The terminating """ should be on its own line, even for ‘one-line’ docstrings (this is a minor departure from PEP 257).
However, black (use of which is increasingly common) understandably enforces PEP 257 and undoes this formatting. The original intent of this divergence from PEP 257 was for convenience in later expanding the one-line docstring into multi-line documentation. Now that one of our semi-common tools disagrees with this divergence, the merits don't seem to warrant the tooling issues.
I therefore propose to replace this rule in the Developer's Guide with:
The terminating """ should be on its own line except for one-line docstrings. If the docstring is a single line, the terminating """ may be either on the same line or on its own line. (Be aware that PEP 257 requires that it be on the same line and black will enforce this rule.)
Attachments
Issue Links
Activity
pydocstyle also complains about this. I'm inclined to think we should allow it. Sometimes we know it's always going to be a single line.
The only worry I have about this is that the justification given seems to apply equally well to almost any divergence from black. Might it be clearer to require black compatibility everywhere?
See also RFC-649...
I would totally upvote an RFC to require black compatibility, although my goal here is more modest. (I noticed this in March of 2020 and only got around to writing the RFC now....)
I'm strongly in favor of this. Let the automated tools do their thing.
I also think it makes sense to allow or encourage black formatting, and that would greatly simplify our code style documentation. In my opinion it's a dreadful waste of our time to argue about formatting and manually format code when an automated tool can do such a fine job. But that sounds like a separate RFC to me. (Note that automated tools to enforce black formatting are now widespread. In particular there is a pytest-black plugin and the pre-commit package supports black).
DMCCB is okay with this RFC as written (the relaxing of the rules).
Russ Allbery please create a Jira implementation ticket for updating the developer guide and then you can adopt this RFC.
Good idea.