Documentation for Cast function is somewhat misleading.

[Keryn Knight]

​Cast docs make use of a Value model, whose definition isn't given, which has a field called integer, which is then referenced via annotate(as_float=Cast('integer', FloatField()))

If you gloss over the previous line, it looks like "integer" is the type to cast into, and as doesn't use output_field as a named argument, it becomes unclear how to adapt it to your own code (this is exactly what has happened for a user on IRC)

Additionally, the docs lead with

We’ll be using the following model in examples of each function

and a definition for an Author, whose age field could be used as the stand-in for the Cast example, instead of the mysterious Value model class (and Value is re-used elsewhere in that page, but not as a random model, but django.db.models.Value)

I think it would be less confusing if it looked something like:

>>> Author.objects.create(age=4, name='Margaret Smith')
>>> msmith = Author.objects.annotate(age_as_float=Cast('age', output_field=FloatField())).get()
>>> print(msmith.age_as_float)
4.0

instead of

>>> Value.objects.create(integer=4)
>>> value = Value.objects.annotate(as_float=Cast('integer', FloatField())).get()
>>> print(value.as_float)
4.0

[Mariusz Felisiak]

​PR

[Mariusz Felisiak <felisiak.mariusz@…>]

In 4cb1545:

Fixed #30958 -- Used a clearer example in the Cast() docs.

[Mariusz Felisiak <felisiak.mariusz@…>]

In 7802553:

[3.0.x] Fixed #30958 -- Used a clearer example in the Cast() docs.

Backport of 4cb15450adac4003ed98f4adcb1710c95fd2b919 from master

[Mariusz Felisiak <felisiak.mariusz@…>]

In f55f89f9:

[2.2.x] Fixed #30958 -- Used a clearer example in the Cast() docs.

Backport of 4cb15450adac4003ed98f4adcb1710c95fd2b919 from master