Social problems of Python doc [was Re: Python docs disappointing]

[Raymond Hettinger]

[Xah Lee]
> i've wrote several articles about this issue, total time spend on this
> is probably more than 2 months full-time work. See:
>
> • Python Documentation Problems
>  http://xahlee.org/perl-python/python_doc_index.html

I just read you post.   You did devote a substantial amount of time
to the project.  Some of your criticisms are valid.  Wish you had
posted patches, I think many of them would have been accepted.

Since you wrote this a few years ago, many examples have
been added to the docs and more are forthcoming.



> I often receive thank you emails for 2 particular articles, which are
> most frequently google searched as indicated by my weblog:
>
> • Python Doc Problem Example: gzip
>  http://xahlee.org/perl-python/python_doc_gzip.html
>
> • Python Doc Problem Example: sort()
>  http://xahlee.org/perl-python/python_doc_sort.html
>
> • Sorting in Python and Perl
>  http://xahlee.org/perl-python/sort_list.html

Some are the criticisms are valid; others seem off-base.

Here are a few thoughts on list.sort() for those who are interested:

* The key= and reversed= parameters are not intended for special
cases, leaving cmp= for the general case.  They were intended to
be full replacements.  In Python3.x, the cmp function is gone.

* The interaction of the key= and cmp= functions can be made to
interact (the key function is first applied to every element and
the cmp function then gets applied to the results of the key
function).  This isn't a normal or intended use case, so the docs
don't delve into the subject.

* The reversed parameter does more than list.sort() followed by
list.reverse().  It also preserves stability in the event of equal
keys:

   >>> sorted([(1,2), (1,3)], key=itemgetter(0), reverse=True)
   [(1,2), (1,3)]

So it was not correct to say that the following are equivalent:

    li.sort(lambda x, y: cmp(x[1],y[1]), reverse=True)
    li.sort(lambda x, y: cmp(y[1],x[1]))

* We should link the sorted() and list.sort() docs to the
sorting how-to (with a fuller discussion on the art of sorting
including a discussion of operator.itemgetter() and
operator.attrgetter() which were designed to work with the key=
parameter.


Raymond