[docs] [issue9364] some problems with the documentation of pydoc

[Eli Bendersky]

New submission from Eli Bendersky <eliben at gmail.com>:

The first paragraph in its documentation says:

"""
In the Python interpreter, do "from pydoc import help" to provide online
help.  Calling help(thing) on a Python object documents the object.
"""

Which is no longer accurate, because the help() function has long ago become a built-in.

Below is an excerpt from Terry Reedy in a private email discussion on this subject, that raises more issues.

---------------------------------------------

1. The output from help(help) could be made more clear.

The nature of 'help' has been a point of confusion. A recent python-list post asked something like "What is 'help'?"

Now (with some parallel examples:

>>> help(int)
Help on class int in module builtins:

class int(object)
[snip]

>>> help(1)
Help on int object:

class int(object)
[snip]

>>> help(help)
Help on _Helper in module site object:

class _Helper(builtins.object)
 |  Define the built-in 'help'.
 |  This is a wrapper around pydoc.help (with a twist).
 |
 |  Methods defined here:
 |
 |  __call__(self, *args, **kwds)
 |

a. 'module site object' is nonsense, it should just be 'module site', except that to be parallel to what is done for other instances, it should be 'Help on _Helper object'. Why should help special-case itself (with a slightly garbled line?) Is that done in site._Helper or pydoc.help?

However, it would be more helpful for all instances to give the location of the class when one asks for help on an instance, just as when one asks for help on the class itself. It is annoying to to have to repeat help(<classname>) just to get that info. So I would like to see
"Help on instance of class int in module builtins:"
"Help on instance of class _Helper in module site:"

This would be a code patch to pydoc.help

b. "This is a wrapper around pydoc.help" good so far
"(with a twist)" thanks a lot. I think the comment should be either removed or explained. A reference manual should explain, not tease.

Replace "Define the built-in 'help'." with something clearer and more accurate, such as "The name 'help' is injected in module builtins after being bound to an instance of this class.". Put this after, not before, the 'wrapper' line.

A patch for site._Helper doc string.


2. Improve manual chapter for site module.

a. It currently starts "Importing this module will append site-specific paths to the module search path." Add "inject 'help' into builtins and " after append. Then add a short explanation paragraph before the search path stuff. Something like

"This module contains a class (_Helper) that wraps function pydoc.help. An instance of the class is bound to name 'help' in the builtins module."

A recent discussion on pydev or maybe python-list (in the thread mentioned above?) implied that one could usefully make another instance of _Helper or maybe a subclass thereof. I did not pay enough attention, though, to really get it.

b. It currently ends with "XXX Update documentation XXX document python -m site –user-base –user-site"

----------
assignee: docs at python
components: Documentation
messages: 111426
nosy: docs at python, eli.bendersky, tjreedy
priority: normal
severity: normal
status: open
title: some problems with the documentation of pydoc
type: behavior
versions: Python 3.1, Python 3.2

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