Bugs item #1511911, was opened at 2006-06-24 16:12 Message generated for change (Comment added) made by akuchling You can respond by visiting: https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1511911&group_id=5470
Please note that this message will contain a full copy of the comment thread, including the initial issue submission, for this request, not just the latest update. Category: Documentation Group: None >Status: Closed >Resolution: Fixed Priority: 5 Submitted By: rurpy (rurpy) >Assigned to: A.M. Kuchling (akuchling) Summary: vague xref in description of sorted() builtin Initial Comment: In section 2.1, "Builtin Functions", in the description of function sorted(), it says: The optional arguments cmp, key, and reverse have the same meaning as those for the list.sort() method. For someone not already very familiar with the organiztion of the Library Reference, a reference to list.sort() is not very useful. If one looks in the index one sees "List Object" and "List, operations on". Although the latter link does bring one to the right page (2.3.6.4 "Mutable Sequence Types") it is not obvious to those not yet used to the loose use of terms in the Puython docs, that "operation" and "method" are synonymous. And God help the poor newbie who forgets the index and tries to find the relevent page using the ToC. I suggest: 1) In sec. 2.1, explicity describe sorted()'s arguments rather than referencing list.sort(). Cut and paste from list.sort. Mention (as a helpful "see also") the existence of the list.sort() method with a link. If that is not acceptable than, 2a) In sec 2.1, change word "method" to "operation", or 2b) In the index under "List", add a link "methods" pointing to section 2.1, (i.e. same target as the currently existing "operations" entry under List. And, 3) In sec 2.1 make the text "List.sorted()" a link to to the List.sorted() page (2.3.6.4 "Mutable Sequence Types") ---------------------------------------------------------------------- >Comment By: A.M. Kuchling (akuchling) Date: 2006-07-03 10:19 Message: Logged In: YES user_id=11375 Thanks for your comment! In rev. 47220, I've copied the description of cmp, reverse, and key, and also improved the xref to give the actual section number. Rev. 47222 applies the change to the 2.4 maintenance branch. ---------------------------------------------------------------------- You can respond by visiting: https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1511911&group_id=5470 _______________________________________________ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
