[docs] [issue8983] Docstrings should refer to help(name), not name.__doc__

[Alexander Belopolsky]

New submission from Alexander Belopolsky <belopolsky at users.sourceforge.net>:

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.");

----------
assignee: docs at python
components: Documentation
messages: 107661
nosy: belopolsky, docs at python, mark.dickinson
priority: normal
severity: normal
stage: needs patch
status: open
title: Docstrings should refer to help(name), not name.__doc__
type: feature request

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue8983>
_______________________________________