homepage

Inspired by issue issue8973, 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.");
Modules/pwdmodule.c:103:See pwd.__doc__ for more on password database entries.");
Modules/pwdmodule.c:124:See pwd.__doc__ for more on password database entries.");
Modules/pwdmodule.c:155:See pwd.__doc__ for more on password database entries.");
Modules/spwdmodule.c:111:See spwd.__doc__ for more on shadow password database entries.");
Modules/spwdmodule.c:143:See spwd.__doc__ for more on shadow password database entries.");

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 issue8983.diff patch. I am a bit unsure about __init__ docstring change:
1. Are cases when help(type(x)) differs from help(x) important enough to distinguish in docstring?
2. Do we need a default docstring on __init__ at all? If so, should we keep a reference to class doc which may not be correct? See issue8973.
3. Why __init__ has a default docstring but __new__ and __del__ don't?
4. There are some other inconsistencies in type docstrings. E.g., "__subclasschck__ -> check if an class is a subclass" (misspelling and and missing ()).

1. For old-style class instances, both help(i) and help(type(i)) give the help for the instance type, which is highly unhelpful IMO. Otherwise it seems than both C class instances and regular Python new-style class instances give the class doc for help(i). Summary: help(x) is good, help(type(x)) unnecessary.
2. 3. Magic methods are documented through docs.python.org and eventually ABCs, not docstrings. I see no reason to make an exception for __init__, except if removing its docstring breaks code.
4. There are actually two typos ;) Regarding parens, I personally think it’s not helpful to always put them, since e.g. "len()" is not valid, but my choice is not Python’s.

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.