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
Docstrings should refer to help(name), not name.__doc__ #53229
Comments
Inspired by issue bpo-8973, I did $ grep -in "see.*\.__doc__" Modules/*.c Surprisingly, there were not as many results as I feared. As I explained in the referenced issue, "See name.__doc__", while technically correct, is not user friendly. If you copy name.__doc__ to >>> prompt, you get an ugly repr of a multiline string. I suggest s/name.__doc__/help(struct)/. Here are the grep results Modules/_threadmodule.c:904:Create a new lock object. See LockType.__doc__ for information about locks."); |
A couple more: $ grep -in "see.*\.__doc__" Lib/*.py
Lib/doctest.py:1782: See doctest.__doc__ for an overview.
Lib/inspect.py:162: See isfunction.__doc__ for attributes listing.""" an a really problematic Objects/typeobject.c:5529: "see x.__class__.__doc__ for signature", This affects every class' help and is very confusing when class doecstring does not show the constructor signature. |
I agree, help(obj) is the better advice. Would you prepare a patch? |
Will do. |
Attaching bpo-8983.diff patch. I am a bit unsure about __init__ docstring change:
|
|
Committed in r84106. I left the __init__ docstring issue unresolved because it is orthogonal to the name.__doc__ vs. help(name) issue here. With redundant help(type(x)), the meaning of the docstring is not changed. I am leaving docstrings on magic methods question for a separate issue. |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
bugs.python.org fields:
The text was updated successfully, but these errors were encountered: