search

jdkandersson / flake8-docstrings-complete

Apache License 2.0
12 stars 2 forks source link

Need a way to avoid adding docstring for __init__ #15

Open aannara opened 11 months ago

aannara commented 11 months ago

Currently if __init__ does not have a docstring. We get this error: DCO010 docstring should be defined for a function/ method/ class, more information: https://github.com/jdkandersson/flake8-docstrings-complete#fix-dco010.

Need an ability to avoid adding docstring for __init__.

If this linter is able to detect __init__ and other dunder/magic methods, then it can be added as a new DOC rule and it can be ignored either by flake8 or by the tool itself.

jdkandersson commented 10 months ago

This would be a breaking change due to previous disables people have used not working anymore for magic methods. Before releasing that it would probably be worthwhile to consider the other rule codes. These should be straight forward to implement based on the linked PR. The ones I would consider are:

I would also create a shared function which determines whether a method is a magic method somewhere

vpoulailleau commented 9 months ago

@jdkandersson To my mind, __init__ is a special magic method, considering that several projects merge the class docstring and the __init__ docstring into the class docstring (leading to __init__ having no docstring at all).

For instance, Google styleguide states:

The __init__ method may be documented in either the class level docstring, or as a docstring on the __init__ method itself. Either form is acceptable, but the two should not be mixed. Choose one convention to document the __init__ method and be consistent with it.

So, I think there are 3 cases:

What do you think about the paragraph in Google styleguide?

jdkandersson commented 9 months ago

I think it is a fair request to have a specific rule to target __init__. Personally, I think it is worthwhile to document arguments to __init__ since they are arguments to the constructor. In version 2 of flake8-docstrings-complete it will be possible to disable a specific rule which will remove the requirement for a docstring on __init__, see #23. I also looked at a few other rules and I think it makes sense to treat them differently for magic methods too. I just haven't gotten around to implementing that yet, though #23 should be relatively easy to follow to implement the rest of the rules noted above. PRs welcome 🙂