[docs] [issue22830] functools.cmp_to_key: misleading key function description

[Raymond Hettinger]

Raymond Hettinger added the comment:

I'll add a link to the glossary entry for key function and to the sorting howto.  Also, I'll change "value indicating the position" to "value to be used as the sort key".

The form sentence being discussed should probably remain close to how it is currently written.  It is part of a two sentence paragraph that contrasts cmp functions versus key functions, so the parallel sentence structure is part of what it is trying to communicate.

FWIW, interpreting "value indicating position" as 0, 1, 2, etc isn't incorrect.  That is a possible key function.

In general, I prefer doc changes to be very minor when they have a history of many people reading them correctly; otherwise, we risk moving away from something that was already working pretty well.

----------
assignee: docs at python -> rhettinger
nosy: +rhettinger

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue22830>
_______________________________________