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
24881	order_with_respect_to needs better docs	karyon	karyon	"the model meta option order_with_respect_to is documented (https://docs.djangoproject.com/en/1.8/ref/models/options/#order-with-respect-to), but i found the docs to be incomplete.

it says ""Marks this object as “orderable” with respect to the given field. This is almost always used with related objects to allow them to be ordered with respect to a parent object."" What i don't know is what it actually means for an object to be ""orderable with respect to something"". Also, these sentences only say that something is ""marked"" and they are ""allowed"" to be ordered. Under what circumstances does ordering actually happen? do i need to do something for a queryset of such objects to be ordered? And what does""almost always"" mean, is there anything else this might be used for?
[[BR]]

Also, i kinda expected this feature to order objects only when queried coming from the parent class, e.g. 
{{{
Question.objects.first().answer_set()
}}}
but not order them when doing e.g. 
{{{
Answer.objects.all()
}}}
because the ordering is only with respect to the parent object, right? that this is not the case might be worth mentioning explicitly.

[[BR]]


I read some code and did experiments and from my point of view, what this actually does is:
 - add a ""_order"" field to the model
 - initializing that field when adding an instance, based on the number of other instances with the same parent (not mentioned in the docs)
- add some convenience setters/getters for that field
- set the ""ordering""-option to that field (most important part and not mentioned in the docs)
[[BR]]

I hope that helps!"	Cleanup/optimization	closed	Documentation	1.8	Normal	fixed		karyon	Ready for checkin	1	0	0	0	1	0