Warnings in docstring for constants
Open
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 355
- Forks
- 181
- Avg merge
- 1d 9h
- Merged PRs (30d)
- 3
Description
I have a couple warnings that I don't understand, also because I am doing already what the validator says...
SOME_CONSTANT = 1
"""
summary line.
some explanation.
"""
I get
GL01: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
GL02: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
the same thing also in the case of a single summary line (for which I would argue that these 2 warnings should be disabled by default as per PEP257), doesn't matter if the quotes are on the same line or not.
I am using numpydoc v1.5.0.
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
Reproduce the GL01 and GL02 warnings with the constant docstring examples using numpydoc v1.5.0. Compare the behavior for multiline and single-line summaries with the stated PEP257 expectation, then define the intended default validation behavior and verify both examples against it.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100