[issue8983] Docstrings should refer to help(name), not name.__doc__
New submission from Alexander Belopolsky <belopolsky@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@python components: Documentation messages: 107661 nosy: belopolsky, docs@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@bugs.python.org> <http://bugs.python.org/issue8983> _______________________________________
Alexander Belopolsky <belopolsky@users.sourceforge.net> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8983> _______________________________________
Georg Brandl <georg@python.org> added the comment: I agree, help(obj) is the better advice. Would you prepare a patch? ---------- nosy: +georg.brandl _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8983> _______________________________________
Alexander Belopolsky <belopolsky@users.sourceforge.net> added the comment: Will do. ---------- assignee: docs@python -> belopolsky _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8983> _______________________________________
Alexander Belopolsky <belopolsky@users.sourceforge.net> added the comment: 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 ()). ---------- keywords: +patch stage: needs patch -> commit review versions: +Python 2.7, Python 3.2 Added file: http://bugs.python.org/file17647/issue8983.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8983> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: 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. ---------- nosy: +merwok _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8983> _______________________________________
Alexander Belopolsky <belopolsky@users.sourceforge.net> added the comment: 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. ---------- resolution: -> accepted stage: commit review -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8983> _______________________________________
participants (3)
-
Alexander Belopolsky -
Georg Brandl
-
Éric Araujo