classification
Title: Docstrings should refer to help(name), not name.__doc__
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.2, Python 2.7
process
Status: closed Resolution: accepted
Dependencies: Superseder:
Assigned To: belopolsky Nosy List: belopolsky, docs@python, eric.araujo, georg.brandl, mark.dickinson
Priority: normal Keywords: patch

Created on 2010-06-12 15:26 by belopolsky, last changed 2010-08-16 20:22 by belopolsky. This issue is now closed.

Files
File name Uploaded Description Edit
issue8983.diff belopolsky, 2010-06-12 18:27
Messages (7)
msg107661 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-06-12 15:26
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.");
msg107662 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-06-12 15:32
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.
msg107667 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-06-12 16:10
I agree, help(obj) is the better advice.  Would you prepare a patch?
msg107669 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-06-12 16:15
Will do.
msg107681 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-06-12 18:27
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 ()).
msg107689 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-06-12 19:54
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.
msg114072 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-08-16 20:22
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.
History
Date User Action Args
2010-08-16 20:22:31belopolskysetstatus: open -> closed
resolution: accepted
messages: + msg114072

stage: commit review -> resolved
2010-06-12 19:54:57eric.araujosetnosy: + eric.araujo
messages: + msg107689
2010-06-12 18:27:04belopolskysetfiles: + issue8983.diff
versions: + Python 2.7, Python 3.2
messages: + msg107681

keywords: + patch
stage: needs patch -> commit review
2010-06-12 16:15:28belopolskysetassignee: docs@python -> belopolsky
messages: + msg107669
2010-06-12 16:10:42georg.brandlsetnosy: + georg.brandl
messages: + msg107667
2010-06-12 15:32:04belopolskysetmessages: + msg107662
2010-06-12 15:26:32belopolskycreate