Code

Opened 7 years ago

Closed 7 years ago

#3455 closed (fixed)

Documentation for "choices" should mention "get_FOO_display"

Reported by: ubernostrum Owned by: jacob
Component: Documentation Version: master
Severity: Keywords: choices get_FOO_display
Cc: Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

Description

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.

Attachments (1)

3455.diff (792 bytes) - added by ubernostrum 7 years ago.
Patch pointing out get_FOO_display in "choices" docs

Download all attachments as: .zip

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

Patch pointing out get_FOO_display in "choices" docs

comment:2 Changed 7 years ago by ubernostrum

  • Triage Stage changed from Accepted to Ready for checkin

comment:3 Changed 7 years ago by ubernostrum

  • Has patch set

comment:4 Changed 7 years ago by jacob

  • Resolution set to fixed
  • Status changed from new to closed

(In [4625]) Fixed #3455: added documentation of Model.get_FIELD_display(). Thanks, Ubernostrum.

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as closed
as The resolution will be set. Next status will be 'closed'
The resolution will be deleted. Next status will be 'new'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.