Python education survey

[Chris Angelico]

On Wed, Dec 21, 2011 at 1:45 AM, Rick Johnson
<rantingrickjohnson at gmail.com> wrote:
> Heck for most things,
> considering you have at least basic programming experience, the help
> function is all you need to learn the language.

I know I shouldn't feed the troll, but this is more general.

You cannot learn the _language_ from help() - it's more like a
dictionary. You still need something that explains the grammar, and
you also need to have some ideas of what names to look up.

The help() function in Python is actually not as helpful as could be
desired, in many cases. I think "help()" on its own is probably a good
thing, but... I didn't know about it until I tried it right while
typing up this email. (That's probably my fault more than Python's,
though.)

help(functionname) is usually fairly helpful - but most of that is
just from the function's docstring. Unfortunately help(classname) and
help(modulename) are way too spammy to be much use. Look for instance
at help(decimal.Decimal) - quite a few dunder methods are listed,
uselessly. What does "__deepcopy__(self, memo)" do? What about
"__ge__(self, other, context=None)"? Unless you happen to know that
__ge__ is the greater-than-or-equal function, it's not going to do you
much good to see the method listed. They're just spam, forcing you to
read through more screed to figure out what's going on.

Same, and even worse, with modules - help(decimal) is pages and pages
of text, detailing the exceptions supported etc. Unlike the class's,
though, the module's docstring is actually quite helpful. (It also
hints at what the context=None arguments are on a lot of the methods.)

Please note that this is not a criticism of the decimal module
specifically; and the help() function can't really be written any
other way, short of having it emit ONLY docstrings, and then demand
that module authors maintain perfect class and module docstrings (like
that's gonna happen).

Hmm. Another feature I didn't know about help() - instead of passing
it an object, you can pass it a string. This gets around the fact that
"help(class)" doesn't work - "help('class')" does. I think I should
reword this from "possible feature request" to "does this already
exist", because it probably does... so...

Is there a less spammy documentation utility, in-built into Python?

Chris Angelico