Why should docstrings end with a blank line?
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 355
- Forks
- 181
- Avg merge
- 1d 9h
- Merged PRs (30d)
- 3
Description
The example points out that
If your docstring does extend over multiple lines, the closing three quotation marks must be on a line by itself, preferably preceded by a blank line.
I'm curious if there is any reason for that preference or if it is just picked arbitrarily. It seems a bit unintuitive to me to put that blank line into the docstring. If you want visual separation to the implementation, putting it after the docstring would seem better.
Note that I'm not trying to start a style discussion, I'm just looking for clarification if there's any particular reason for the suggestion. I hope this is the right place to put this sort of question. CC @jnothman, who added the example in e71411db7518fc6c92bfdbb1ca48699521f1b72d.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with doc/example.py at line 9 and inspect commit e71411db7518fc6c92bfdbb1ca48699521f1b72d, then review the surrounding documentation and comment discussion. Done means the documentation clearly explains whether the blank line has a specific rationale or is only a preference.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100