Python doc â3.6.4 Mutable Sequence Typesâ at http://python.org/doc/2.4/lib/typesseq-mutable.html
in which contains the documentation of the âsortâ method of a list. Quote: -------------- .sort([cmp[, key[, reverse]]]) sort the items of s in place (7), (8), (9), (10) ... (8) The sort() method takes optional arguments for controlling the comparisons. cmp specifies a custom comparison function of two arguments (list items) which should return a negative, zero or positive number depending on whether the first argument is considered smaller than, equal to, or larger than the second argument: "cmp=lambda x,y: cmp(x.lower(), y.lower())" key specifies a function of one argument that is used to extract a comparison key from each list element: "cmp=str.lower" reverse is a boolean value. If set to True, then the list elements are sorted as if each comparison were reversed. In general, the key and reverse conversion processes are much faster than specifying an equivalent cmp function. This is because cmp is called multiple times for each list element while key and reverse touch each element only once. Changed in version 2.3: Support for None as an equivalent to omitting cmp was added. Changed in version 2.4: Support for key and reverse was added. ------------------ As a piece of documentation, this is a relatively lousy one. The question Python doc writers need to ask when evaluating this piece of doc are these: * can a experienced programer (expert at several languages) who is new to Python, and also have read the official Python tutorial, can he, read this doc about âsortâ, and know exactly how to use it with all the options? * can this piece of documentation be rewritten fairly easily, so that the answer to the previous question is a resounding yes? To me, the answers to the above questions are No and Yes. Here are some issues with the doc: * in the paragraph about âKeyâ, the illustration given is: âcmp=str.lowerâ. Shouldn't it be âkey=str.lowerâ? * This doc lacks examples. One or two examples will help a lot, especially to less experienced programers. (which comprises the majority of readers) In particular, it should give a full example of using the cmp predicate and one with key. * This doc fails to address what happens when the predicate and the short cut version conflicts. e.g. myList.sort(lambda x,y: cmp(x[0], y[0]), lambda x: str(x[0]), False ) * on the whole, the way this doc is written does not give a clear picture of what exactly is happening (think of mathematics) with sort, nor the roles of the supplied options, nor how to use them. Quick remedy: add a examples of using cmp predicate. And a example using âkeyâ predicate. Add example of Using one of them and with reverse. (the examples need not to come with much explanations. One sentence annotation will do. ) Other than that, the way the doc is layed out with a terse table and run-on footnotes (as appeared in other pages) is not inductive. For a better improvement, there needs to be overhaul of the organization and the attitude of the entire doc. The organization needs to be programing based, as opposed to implementation or computer science based. (in this regard, one can learn from the Perl folks). As to attitude, the writing needs to be Python-as-is, as opposed to computer science framework. I'll might have to give more details in the future, but I've made some headway in this respect before; peruse: http://xahlee.org/Periodic_dosage_dir/t2/xlali_skami_cukta.html Xah [EMAIL PROTECTED] â http://xahlee.org/PageTwo_dir/more.html â -- http://mail.python.org/mailman/listinfo/python-list