New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Introduce D107 code for missing __init__ docstring #277

Merged
merged 5 commits into from Aug 31, 2017

Conversation

Projects
None yet
3 participants
@tjanson
Copy link
Contributor

tjanson commented Aug 28, 2017

As described in #273, it would be useful to have a separate error code for missing docstrings on __init__ methods (which currently fall under D102).
This PR introduces D107 for this purpose.

This enables the user to use only class docstrings (as described by this Google style) by ignoring D107.

@Nurdok

This comment has been minimized.

Copy link
Member

Nurdok commented Aug 29, 2017

The code itself looks good to me and I am inclined to merge this, but I have a thought - isn't the same reasoning for having a separate error code for __init__ also applies to the other variadic magic methods (i.e., __call__ and __new__)? For example, I can also see how __call__ would be documented in the class docstring instead of in the __call__ method docstring.

So, I am considering applying this to all variadic magic methods and changing the error description accordingly. Any thoughts?

/cc @FarmerSez

@shacharoo

This comment has been minimized.

Copy link
Member

shacharoo commented Aug 29, 2017

I tend to disagree @Nurdok .
__init__ always constructs an object, and usually they way it's done is pretty boring to document.
If someone had overridden __call__ or __new__, something interesting is going on, and I'd like to see documentation for that wizardry within the method. That doesn't mean that there shouldn't be any general documentation to that behavior in the class's docstring - there should, but I expect more info within the method.

For example, you know how django models work. Wouldn't you like to see a docstring for that __new__ method? (line 73)

@tjanson

This comment has been minimized.

Copy link
Contributor

tjanson commented Aug 29, 2017

Yeah, I agree @FarmerSez. I definitely think __init__ should be treated separately, by itself.

It certainly doesn't hurt to have an extra code for the remaining variadic magic methods, but I personally don't need that. If I were you I'd handle it just like this case: Accept a PR if someone comes along and wants that feature, but don't (pro-)actively implement it.

@Nurdok Nurdok merged commit de24da6 into PyCQA:master Aug 31, 2017

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment