Documentation for "choices" should mention "get_FOO_display"
|Reported by:||ubernostrum||Owned by:||jacob|
|Cc:||Triage Stage:||Ready for checkin|
|Has patch:||yes||Needs documentation:||no|
|Needs tests:||no||Patch needs improvement:||no|
The documentation for the choices attribute on model fields mentions that choices should be a tuple of 2-tuples, including an actual value and a human-readable name, but documentation on how to retrieve the human-readable name of the selected choice from an instance of the model lives elsewhere, in the database API documentation, under the unintuitive name of get_FOO_display. This hinders a new user of Django trying to understand how best to make use of choices.
At the very least, the model documentation should include, under choices, a link to the get_FOO_display entry in the DB documentation for an explanation of how to get the human-readable name back out of a model instance. Ideally, we'd do that and come up with better titles for the sections on the various get_FOO_display/get_next_by_FOO/etc. methods.
Change History (5)
comment:1 Changed 7 years ago by ubernostrum
- Needs documentation unset
- Needs tests unset
- Patch needs improvement unset
- Triage Stage changed from Unreviewed to Accepted
Changed 7 years ago by ubernostrum
comment:2 Changed 7 years ago by ubernostrum
- Triage Stage changed from Accepted to Ready for checkin