[2.0.x] Fixed #29313 -- Doc'd how to use F() to sort null values.

Backport of 5d923f2d8cadb06497d255097caa4583d66b697a from master

1 files changed, 17 insertions, 0 deletions

diff --git a/docs/ref/models/expressions.txt b/docs/ref/models/expressions.txt
index 5e230bb918..26ce4bd07a 100644
--- a/docs/ref/models/expressions.txt
+++ b/docs/ref/models/expressions.txt
@@ -220,6 +220,21 @@ primary key value rather than a model instance::
     >> car.built_by
     3
 
+.. _using-f-to-sort-null-values:
+
+Using ``F()`` to sort null values
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use ``F()`` and the ``nulls_first`` or ``nulls_last`` keyword argument to
+:meth:`.Expression.asc` or :meth:`~.Expression.desc` to control the ordering of
+a field's null values. By default, the ordering depends on your database.
+
+For example, to sort companies that haven't been contacted (``last_contacted``
+is null) after companies that have been contacted::
+
+    from django.db.models import F
+    Company.object.order_by(F('last_contacted').desc(nulls_last=True))
+
 .. _func-expressions:
 
 ``Func()`` expressions
@@ -969,6 +984,7 @@ calling the appropriate methods on the wrapped expression.
         Returns the expression ready to be sorted in ascending order.
 
         ``nulls_first`` and ``nulls_last`` define how null values are sorted.
+        See :ref:`using-f-to-sort-null-values` for example usage.
 
         .. versionchanged:: 1.11
 
@@ -979,6 +995,7 @@ calling the appropriate methods on the wrapped expression.
         Returns the expression ready to be sorted in descending order.
 
         ``nulls_first`` and ``nulls_last`` define how null values are sorted.
+        See :ref:`using-f-to-sort-null-values` for example usage.
 
         .. versionchanged:: 1.11