search

jsh9 / pydoclint

A Python docstring linter that checks arguments, returns, yields, and raises sections
https://pypi.org/project/pydoclint/
MIT License
151 stars 15 forks source link

Docs request: more info on `allow-init-docstring` #98

Closed jamesbraza closed 1 year ago

jamesbraza commented 1 year ago

I am sort of curious with this one, why is allow-init-docstring defaulted to False in 0.3.8?

PEP 257 talks about __init__ needing a docstring, so I am wondering why this tool chose to deviate from PEP 257 in its default behavior?

This default piqued my curiosity. If you wouldn't mind, can you link docs on why __init__ docstrings are discouraged?

jsh9 commented 1 year ago

Without this flag, it's possible for users to put docstrings both under __init__() and under class XXX, which creates ambiguity. But some users also said they explicitly needed to put docstrings in those two places for different purposes.

In most of my use cases, I put all the introduction of the class and the class attributes under class XXX. That's why I set this flag to False by default.

jamesbraza commented 1 year ago

Huh okay, gotchu and thanks!

For reference, when black makes a stylistic choice behind a default, they document their logic: https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#line-length. Since encouraging no docstrings in __init__ is a stylistic choice that deviates from Python's docstring style PEP (PEP 257), maybe it'd be worth to write up a little doc explaining it.

Otherwise, feel free to close this out, thanks for answering

jsh9 commented 1 year ago

I updated the doc to explain why the default is False: https://github.com/jsh9/pydoclint/commit/55c0fdec67698bee7bba91d2b2481e564a1d6139