-
Notifications
You must be signed in to change notification settings - Fork 1.1k
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
Autofix remove types from docstring #9070
Comments
For the same reasoning we also dropped type information from our docstrings. The redundancy is error prone and adds little information. Another similar rule would be type docstrings for classes, where the type hint can be provided by instance variable annotations (example) |
Great idea! At work, we switched to |
Also PEP 727 maybe could change the way of how to document parameters. then, after it standardized, we need to remove junks from docstrings. |
In order to implement an autofix, a new rule is needed first, right? Something like
I think that is orthogonal to this issue and should be treated separately, once PEP 727 has been accepted. The rule could be something like |
This seems reasonable to me! Although we do not yet have a dedicated docstring parser and may want to wait until we write one. |
See also #458 |
Currently types can be added in two places in a function as a type hint and in the documentation.
This can lead to potential conflict between the type hint and the docstring leading to multiple sources of truth. #5541 seeks to solve this by fixing the docstring, however this could still lead to the reverse issue; that the docstring is updated but not the type hint. It also avoid duplicating information. The reason to prioritise the type hint is meaningful as it can be checked by type hinters etc.
There might still be reasons to have types in the docstring such as documentation, but there already exist extension which remedy this need (e.g. https://pypi.org/project/sphinx-autodoc-typehints/). I probably wouldn't set it as a default though.
Let me know if there is something I have missed. I very much enjoy the package.
Edit: In a similar vein, it might also be worth discouraging "Defaults to {value}" in the docstring as it similar can be outdated and is already specified function signature.
The text was updated successfully, but these errors were encountered: