id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
30958	Documentation for Cast function is somewhat misleading.	Keryn Knight	Farhaan Bukhsh	"[https://docs.djangoproject.com/en/dev/ref/models/database-functions/#django.db.models.functions.Cast 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
}}}"	Cleanup/optimization	closed	Documentation	dev	Normal	fixed			Accepted	1	0	0	0	1	0