Refs #23386 -- Documented that F() expressions are applied on each model.save()

1 files changed, 16 insertions, 0 deletions

diff --git a/docs/ref/models/expressions.txt b/docs/ref/models/expressions.txt
index 6b1df0d937..a07b57e815 100644
--- a/docs/ref/models/expressions.txt
+++ b/docs/ref/models/expressions.txt
@@ -166,6 +166,22 @@ robust: it will only ever update the field based on the value of the field in
 the database when the :meth:`~Model.save()` or ``update()`` is executed, rather
 than based on its value when the instance was retrieved.
 
+``F()`` assignments persist after ``Model.save()``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``F()`` objects assigned to model fields persist after saving the model
+instance and will be applied on each :meth:`~Model.save()`. For example::
+
+    reporter = Reporters.objects.get(name='Tintin')
+    reporter.stories_filed = F('stories_filed') + 1
+    reporter.save()
+
+    reporter.name = 'Tintin Jr.'
+    reporter.save()
+
+``stories_filed`` will be updated twice in this case. If it's initially ``1``,
+the final value will be ``3``.
+
 Using ``F()`` in filters
 ~~~~~~~~~~~~~~~~~~~~~~~~