Issue 22830: functools.cmp_to_key: misleading key function description (original) (raw)

https://docs.python.org/3.4/library/functools.html#functools.cmp_to_key says " A key function is a callable that accepts one argument and returns another value indicating the position in the desired collation sequence." A python list poster (Veek M) 'value indicating the position' as meaning 0, 1, 2, ... and I would read it that way if I did not know better.

Entries for min() and max() say "The key argument specifies a one-argument ordering function like that used for list.sort()." This would be reused here. We also, now, have a Glossary entry for 'key function'. This could be referred to instead.

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.