Opened 4 years ago

Closed 4 years ago

Last modified 3 years ago

#14403 closed (fixed)

Missing/incomplete documentation for FloatField?

Reported by: typeshige <typeshige@…> Owned by: trebor74hr
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 trebor74hr 4 years ago.
models/fields.txt - distinction between float and decimal
14403_decimalFloat.diff (1.4 KB) - added by trebor74hr 4 years ago.
models/fields.txt - distinction between float and decimal
14403_decimalFloat.3.diff (1.4 KB) - added by dmedvinsky 4 years ago.
Little fix for patch from trebor74hr

Download all attachments as: .zip

Change History (16)

comment:1 Changed 4 years ago by gabrielhurley

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Resolution set to invalid
  • Status changed from new to closed

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 4 years ago by typeshige <typeshige@…>

  • Resolution invalid deleted
  • Status changed from closed to reopened

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 follow-up: Changed 4 years ago by gabrielhurley

  • Resolution set to wontfix
  • Status changed from reopened to closed

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 4 years ago by carljm

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 4 years ago by gabrielhurley

  • Resolution wontfix deleted
  • Status changed from closed to reopened
  • Triage Stage changed from Unreviewed to Accepted

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 4 years ago by trebor74hr

  • Owner changed from nobody to trebor74hr
  • Status changed from reopened to new

comment:7 Changed 4 years ago by trebor74hr

  • Status changed from new to assigned

Changed 4 years ago by trebor74hr

models/fields.txt - distinction between float and decimal

Changed 4 years ago by trebor74hr

models/fields.txt - distinction between float and decimal

comment:8 Changed 4 years ago by trebor74hr

  • Has patch set

Changed 4 years ago by dmedvinsky

Little fix for patch from trebor74hr

comment:9 Changed 4 years ago by trebor74hr

  • Triage Stage changed from Accepted to Ready for checkin

comment:10 Changed 4 years ago by trebor74hr

  • Triage Stage changed from Ready for checkin to Accepted

comment:11 Changed 4 years ago by gabrielhurley

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

(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 4 years ago by gabrielhurley

(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 3 years ago by jacob

  • milestone 1.3 deleted

Milestone 1.3 deleted

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