[Python-checkins] r70438 - python/trunk/Doc/library/functions.rst

[Raymond Hettinger]

[MvL]
> I hear frequent complaints that this style of documentation is unusable
> to casual users. They don't want a specification of an API; they want to
> know how to use it. And they don't want to filter that out of the
> tutorial, but they want to see how to use it when they read the API.
> So examples *must* go along with the specification.

Of course, we're in complete agreement.  I've included that much in
almost all the docs I've written (all of collections.rst, the examples
in the Queue module, the thorough docs with examples in itertools).

There is however a matter of economy of expression and not having
lengthy examples with low information content.  At some point,
verbosity defeats its own goal of being communicative.
Fred Drake used to put a good did of editorial review into the docs
but that seems to have gone out the window.   Cut and pasting
console sessions like the one we're talking about has a breezy, 
wiki-like feel that doesn't show that someone made an effort
to focus their thoughts and produce a minimal, motivating example.

For the second argument for iter(), there are good, succinct
motivating examples such as converting file reads (which terminate
with an empty string) into iterators.  The example currently listed
is just a toy that makes the optional argument look silly.

If there are going to be examples, they should be good ones.


Raymond