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")
|