Missing/incomplete documentation for FloatField?

[typeshige <typeshige@…>]

​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/

[Gabriel Hurley]

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!

[typeshige <typeshige@…>]

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.

[Gabriel Hurley]

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!

[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.

[Gabriel Hurley]

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.

[Robert Lujo]

models/fields.txt - distinction between float and decimal

[Robert Lujo]

models/fields.txt - distinction between float and decimal

[dmedvinsky]

Little fix for patch from trebor74hr

[Gabriel Hurley]

(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.

[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.

[Jacob]

Milestone 1.3 deleted