order_with_respect_to needs better docs

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

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.

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)

I hope that helps!

[Tim Graham]

Thanks for the suggestions. It would be even more helpful if you could submit a patch with proposed changes.

[Tim Graham <timograham@…>]

In 27c839e0:

Fixed #24881 -- Clarified Meta.order_with_respect_to documentation

[Tim Graham <timograham@…>]

In aa00f482:

[1.8.x] Fixed #24881 -- Clarified Meta.order_with_respect_to documentation

Backport of 27c839e0fce99254ad61322bb827a821f832e840 from master