[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 -- http://mail.python.org/mailman/listinfo/python-list
