[Python-ideas] doc anomalies

[Steven D'Aprano]

On Mon, Apr 13, 2015 at 10:51:05AM +0530, Rustom Mody wrote:

> In python3 please check
> help()
> followed by
> PACKAGES
> and
> DYNAMICFEATURES
> 
> Do those help texts look helpful/meaningful?

PACKAGES certainly looks helpful and meaningful, if it were reached via 
IMPORTING instead :-)

If I wanted to know about packages, and got five pages of text about 
importing, I would be rather confused and annoyed.

I would like to see PACKAGES lead to a short description of packages and 
their structure, the special role of __init__.py and __main__.py, and, 
hmmm, I think they are called "namespace packages"? They're a fairly new 
feature, and I've never used them. It may also include "See also 
IMPORT."

DYNAMICFEATURES is also useful, though less useful than it could be due 
to excessive jargon that isn't defined. What's a free variable? Can we 
see examples of what dynamic features can and cannot be used?

I actually expected to see a lot more dynamic features discussed:

- getattr, setattr, delattr
- exec
- eval
- compile
- introspection via the inspect module, dir and vars
- Python equivalents to Java-like "reflection"

and probably more, but that may just mean my idea of dynamic features 
are different to the author of that help text.


> Is this the right list for such questions?

Personally, I would have started by asking on the python-list list 
(comp.lang.python) and then gone straight to raising an issue on the 
bugtracker, if there was an issue to raise.

But since we're here, a few comments come to mind for discussion...

(1) Help topics seem to be case sensitive. That's not very helpful:

help> packages
no Python documentation found for 'packages'

help> PACKAGES
[masses of text]

(2) Hitting the enter key with nothing on the help? prompt exits help. 
That's downright ugly.

(3) Does help() have an "apropos" or "search" feature, for searching the 
bodies of help pages for keywords?


-- 
Steve