Related fields docs improvements

[Anssi Kääriäinen]

The docs at ​https://docs.djangoproject.com/en/dev/ref/models/relations/ say that "In the example above, e.save() is called to perform the update." However, the example above doesn't contain .save() call at all.

In addition it might be worth it to note that all of the methods apply the change to the database instantly.

Still, I don't see a mention of direct association, that is e.entry_set = some_list. This is often the fastest way to update a relationship.

Creating separate patches for these issues might be better than doing them all in one go.

[Tim Graham]

What's meant by the first sentence is that when you execute b.entry_set.add(e), Django calls e.save() to perform the update. I guess this can be clarified if it isn't clear.

[Anssi Kääriäinen]

Nah, no need to do that, I just didn't manage to read that correctly.

[Daniele Procida]

So improvements still in order include:

• a mention of direct association, that is e.entry_set = some_list, which is often the fastest way to update a relationship.
• a note that all the methods discussed - add, create, remove, clear - apply database changes immediately

[Matthew Rich]

Tackling this ticket at Djangocon sprints.

[Matthew Rich]

Pull request submitted.

[Aymeric Augustin]

Please don't mark tickets as fixed until a fix is actually merged in the master branch; use the "has patch" flag instead. Thank you!

[Tim Graham]

merged in ffe21e1f40b99d82d441eb46de323c6bfb0687e9 and 38d2e7c22592f8c06fb961cfaee2f8309857e7c0