PyWart: Itertools module needs attention

[rantingrick]

On Sep 13, 10:45 am, Ian Kelly <ian.g.ke... at gmail.com> wrote:

> Have you looked at the online itertools documentation at all?
>
> http://docs.python.org/library/itertools.html

Yes the online docs are much better. I really like the source code
showing the inner workings of the methods. However i always get upset
when i see poorly thought out doc-strings. My philosophy is that we
should use the built in help function first and only visit the
documentation if more instruction is needed.


I may need to create another PyWart on the topic of doc-strings and
how the author of these strings needs to forget everything he knows
and imagine he is a complete python neophyte. I remember my initial
frustrations learning about functions (in another life it seems) and
my inability to grasp the concept was due to poor examples. I believe
the author use the Fibonacci sequence as an example (Python docs use
this example also). What an idiot!

What does conditionals, linear assignment, loops, the print function,
in-place addition, logic, blah, blah, have to do with understanding a
function... NOTHING! The most basic and by far the best first example
for functions (in any language) is this...

def add(x, y):
    return x + y

Followed by this...

def sub(x,y):
    return x - y

Simple and to the point. It simply reeks of "ah ha"! I dare anyone to
create a better introductory function example. Dear Tutorial Writer:
When writing tutorials please check your ego at the door. Thank you.