-
Notifications
You must be signed in to change notification settings - Fork 1.2k
New issue
Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? # to your account
Clarify that D417 only checks docstrings with an arguments section #16494
Conversation
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I added one comment, but thanks for doing this!
/// This rule does not check functions without any arguments sections (e.g. `Args`). | ||
/// | ||
/// This rule is enabled when using the `google` convention, and disabled when | ||
/// using the `pep257` and `numpy` conventions. | ||
/// Note that this rule only checks docstrings with an arguments (e.g. `Args`) section. | ||
/// Docstrings without any arguments sections |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This line looks like it might have gotten cut off somehow. And did you want to remove the note about the google
convention? It is mentioned earlier in the docs, but this seems to add a little more clarification.
I think the change on 1170 might be enough here. (actually I slightly prefer line 1172, but either of those on line 1170 would be great)
I can't add a suggestion on deleted lines, but my suggestion is:
/// Note that this rule only checks docstrings with an arguments (e.g. `Args`) section.
///
/// This rule is enabled when using the `google` convention, and disabled when
/// using the `pep257` and `numpy` conventions.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
And did you want to remove the note about the google convention?
Definitely not. Thanks for catching this!
7cab740
to
59dd160
Compare
Summary
This came up in #16477
It's not obvious from the D417 rule's documentation that it only checks docstrings
with an arguments section. Functions without such a section aren't checked.
This PR tries to make this clearer in the documentation.