Improve ChoiceField.choices documentation

[chgad]

Hi,
i just now stumbled upon that the ChoiceField accepts the choices as tuples (value, display_name) like documented here. As in this issue #4082, i was very surprised that the representation is the value not the display_nameprovided in the choices.
So:

1. It would be nice to document this explicitly.
2. Why is the behavior defined this way?

I'd expect the display_name as the representation for a given value why else should i define the display_name then? The issue mentioned above was briefly answered with a quote form the django docs which, in my eyes, would point towards my expected behavior.
Especially if your API serves a detached frontend app. This app would need the choices-dict too for the correct display of the possible abstract values. Thus leading to code duplication.

[denolehov]

You can find choice values and display values in the response from OPTIONS (metadata) request.

I would say that serializing choice field values to values instead of display_names makes more sense in the context of APIs, since they're intended to be used programmatically.

If your particular use-case requires display_names, you can inherit choice field and override its .to_representation() method.

[rpkilby]

@denolehov is correct. The value is intended to be used programmatically, while display_name is intended for display purposes. Display values aren't suitable for API use, as they may be translated based on the user's locale.

I've gone into more detail in #6854 (comment), but in short, it would be nice if there was some construct that differentiated DB values, API representation, and display values.