Opened 6 years ago

Closed 6 years ago

Last modified 5 years ago

#14403 closed (fixed)

Missing/incomplete documentation for FloatField?

Reported by: typeshige <typeshige@…> Owned by: Robert Lujo
Component: Documentation Version: 1.2
Severity: Keywords:
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

Description

http://docs.djangoproject.com/en/dev/ref/models/fields/#floatfield

There is no description of options for model floatfields.

It invites people to read the release notes for 1.0 for changes, but there is no description of what changed as far as I can see.

http://docs.djangoproject.com/en/dev/releases/1.0/

Attachments (3)

14403_decimalFloat.2.diff (1.4 KB) - added by Robert Lujo 6 years ago.
models/fields.txt - distinction between float and decimal
14403_decimalFloat.diff (1.4 KB) - added by Robert Lujo 6 years ago.
models/fields.txt - distinction between float and decimal
14403_decimalFloat.3.diff (1.4 KB) - added by dmedvinsky 6 years ago.
Little fix for patch from trebor74hr

Download all attachments as: .zip

Change History (16)

comment:1 Changed 6 years ago by Gabriel Hurley

Needs documentation: unset
Needs tests: unset
Patch needs improvement: unset
Resolution: invalid
Status: newclosed

The "Changed in version 1.0" marker is going to be removed in 1.3 (ticket #14000). Otherwise, what would you have the documentation say? If you look at the code for a FloatField there's almost nothing happening. It's nearly as close to a vanilla Field subclass as you can get.

There are several other field classes that have very short descriptions in that document (BooleanField, for example). It's a conscious decision not to list all valid options for every field, and instead to only list the common options once at the top of the page.

If there is specific info you feel needs to be added, please re-open the ticket with more specifics (and ideally a patch). Thanks!

comment:2 Changed 6 years ago by typeshige <typeshige@…>

Resolution: invalid
Status: closedreopened

This makes sense. Thank you.

Actually, after writing this ticket, I found out that I was thinking of DecimalField which has documented options. I got it confused with FloatField.

Since these are somewhat similar, perhaps they can refer to each other since they don't appear closely together in the docs. Kind of like how BigIntegerField refers to IntegerField.

comment:3 Changed 6 years ago by Gabriel Hurley

Resolution: wontfix
Status: reopenedclosed

The field classes in that document are listed in alphabetical order rather than by type or similarity. This issue has actually come up before though I can't find the ticket currently. The core of the decision is that things in the Reference section of the docs are meant to be comprehensive listings (which should be ordered alphabetically) rather than guided overviews (which would be better grouped by topic, and hence are in the Topics section).

While I realize that many people come to the Reference section without realizing what they're looking at, without a major reorganization and restructuring of the docs, this isn't an issue which will be fixed.

Ultimately, DecimalField and FloatField aren't actually that related from a Python standpoint. To us mere humans they both store numbers with decimal points in them, but to computers they're very different.

I hope that all makes sense, and thanks for the report!

comment:4 in reply to:  3 Changed 6 years ago by Carl Meyer

Replying to gabrielhurley:

Ultimately, DecimalField and FloatField aren't actually that related from a Python standpoint. To us mere humans they both store numbers with decimal points in them, but to computers they're very different.

Documentation is for humans. This paragraph is an excellent argument for the cross-link and clarification requested in the reopen, not against it. When two things that seem superficially similar to the newbie are actually quite different underneath, that's what docs are for.

comment:5 Changed 6 years ago by Gabriel Hurley

Resolution: wontfix
Status: closedreopened
Triage Stage: UnreviewedAccepted

I suppose that's fair; though what needs to be understood is actually a Python issue, not a Django issue. I'll accept that we could offer some guidance on the topic.

Perhaps just a link to the Decimal module's comparison of Decimal vs. float in the Python docs, linked from both DecimalField and FloatField, would suffice? I don't see it as beneficial to try and explain the difference between a float and a Decimal within the ModelField Reference.

comment:6 Changed 6 years ago by Robert Lujo

Owner: changed from nobody to Robert Lujo
Status: reopenednew

comment:7 Changed 6 years ago by Robert Lujo

Status: newassigned

Changed 6 years ago by Robert Lujo

Attachment: 14403_decimalFloat.2.diff added

models/fields.txt - distinction between float and decimal

Changed 6 years ago by Robert Lujo

Attachment: 14403_decimalFloat.diff added

models/fields.txt - distinction between float and decimal

comment:8 Changed 6 years ago by Robert Lujo

Has patch: set

Changed 6 years ago by dmedvinsky

Attachment: 14403_decimalFloat.3.diff added

Little fix for patch from trebor74hr

comment:9 Changed 6 years ago by Robert Lujo

Triage Stage: AcceptedReady for checkin

comment:10 Changed 6 years ago by Robert Lujo

Triage Stage: Ready for checkinAccepted

comment:11 Changed 6 years ago by Gabriel Hurley

Resolution: fixed
Status: assignedclosed

(In [15090]) Fixed #14403 -- Provided some extra resources on the difference between FloatField and DecimalField in the model field reference. Thanks to typeshige for the report and trebor74hr and dmedvinsky for the draft patch.

comment:12 Changed 6 years ago by Gabriel Hurley

(In [15091]) [1.2.X] Fixed #14403 -- Provided some extra resources on the difference between FloatField and DecimalField in the model field reference. Thanks to typeshige for the report and trebor74hr and dmedvinsky for the draft patch.

Backport of [15090] from trunk.

comment:13 Changed 5 years ago by Jacob

milestone: 1.3

Milestone 1.3 deleted

Note: See TracTickets for help on using tickets.
Back to Top