Terry J. Reedy <[email protected]> added the comment:
The immediate issue is improvement of the entries for help and help():
In builtin functions section:
Expand "Invoke the built-in help system." to
"Invoke the built-in help system, which uses *pydoc*."
where *pydoc* is linked to the pydoc section.
Add to the end of the entry something like "As needed, pydoc imports modules to
get their doc strings."
The special string 'modules' is not documented in the manual entry for help()
itself. That is fine. It does appear in the longer text that appears for
'help()'. That text, where ever it is, could and should have a warning.
"Warning: gathering the results for the topic 'modules' can take considerable
time and have side effects as it imports *every* module available to get at its
doc string."
A separate issue would be a feature request to not do that (assuming it really
does). Given that 'modules' just produces a list of (incomplete) module names,
I do not see the point of importing until one requests help on a particular
name.
There seems to be a bug. In a fresh 3.2.2 IDLE window, help('modules') produces
about 300 names. If I repeat, I get a reduced list of 58 names. These seem to
just be the builtin C-coded modules, like 'math', with all Python-coded
modules, like 'random', omitted.
----------
assignee: -> docs@python
components: +Documentation
nosy: +docs@python, terry.reedy
stage: -> needs patch
versions: +Python 2.7, Python 3.2, Python 3.3
_______________________________________
Python tracker <[email protected]>
<http://bugs.python.org/issue12902>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
