Optional checks for multi-line docstring summary style. #174
Conversation
toroettg
changed the title
|
Thanks for submitting this! The concept is good, and I'll try to review the code as soon as I can. |
|
|
||
| @expect('D212: Multi-line docstring summary does not start on the first line.') | ||
| def multi_line_starts_second_line(): | ||
| """ |
There was a problem hiding this comment.
could you add some tests that use u"""...""" , r"""...""" ,etc. I suspect that if first not in ['"""', "'''"]: wont catch them all.
|
Fwiw, it was on my todo list; my main project wants to stablise our docstrings according to your D212 rule ;-) So I am thrilled to see this patch. When you get a chance, please squash your two commits into a single commit. Thanks. Just as an aside, I believe D213 equals H404. https://github.com/openstack-dev/hacking/blob/master/hacking/checks/docstrings.py#L77 |
toroettg
force-pushed
the
MultiLineStyleOption
branch
from
e952a9f to
973d8d1
Compare
|
You are right, I've added additional checks, but they quickly grow tedious. Another Another enhancement for the test framework, which came to my mind, was to test against virtual files, whose content is generated dynamically at run time from definitions in test cases. H404 seems to be equal to D212; I have somewhat harmonized this PR with their code, since I am reinventing the wheel already. Kind regards, |
That would be very nice. It would be a separate changeset. |
| @@ -14,4 +14,4 @@ Not all error codes are checked for by default. The default behavior is to | |||
| check only error codes that are part of the `PEP257 | |||
| <http://www.python.org/dev/peps/pep-0257/>`_ official convention. | |||
|
|
|||
| All of the above error codes are checked for by default except for D203. | |||
| All of the above error codes are checked for by default except for D203, D212 and D213. | |||
There was a problem hiding this comment.
Please make sure you don't exceed 80 columns per line.
|
Make sure to also add your change to the changelog. |
toroettg
force-pushed
the
MultiLineStyleOption
branch
from
973d8d1 to
53ff113
Compare
|
I have adapted the PR to your requested changes. With the integration as a regular definition test, I had to remove the Unicode related test cases, since they are invalid in the current PyPy3 (v2.4.0). Those may be added to #178 if so desired. Also, the |
|
@toroettg Merged! Thank you so much for your time and effort, and sorry for taking so long to merge this. |
Hello,
PEP 257 allows multi-line docstring summaries to start on the first or second line, as it is outlined in #44. I prefer one over the other and was looking for a way to perform consistency checks on my projects. Thus, I have added two optional error codes (D212, D213), which you might like to incorporate.
As those are more restrictive than PEP 257, both error codes should naturally be selected explicitly (and typically mutual exclusive) by the following. Otherwise, they are ignored.
I have tried to touch as little as possible when implementing them. Please review if this is too cumbersome, or interferes with pydocstyle in a way I have not noticed.
Kind regards,
Tobias