From b1c1fd33ed7a1192050b25bd0a256a97326d7692 Mon Sep 17 00:00:00 2001
From: Natalia <124304+nessita@users.noreply.github.com>
Date: Thu, 20 Mar 2025 12:21:31 -0300
Subject: [PATCH] Improved and reorganized querystring template tag docstring
 and ref docs.

---
 django/template/defaulttags.py  | 19 ++++++++++---------
 docs/ref/templates/builtins.txt | 22 +++++++++++-----------
 2 files changed, 21 insertions(+), 20 deletions(-)

diff --git a/django/template/defaulttags.py b/django/template/defaulttags.py
index 9023bcc87d..a7885e541a 100644
--- a/django/template/defaulttags.py
+++ b/django/template/defaulttags.py
@@ -1175,24 +1175,25 @@ def now(parser, token):
 @register.simple_tag(name="querystring", takes_context=True)
 def querystring(context, query_dict=None, **kwargs):
     """
-    Add, remove, and change parameters of a ``QueryDict`` and return the result
-    as a query string. If the ``query_dict`` argument is not provided, default
-    to ``request.GET``.
+    Build a query string using `query_dict` and `kwargs` arguments.
+
+    This tag constructs a new query string by adding, removing, or modifying
+    parameters, starting from the given `query_dict` (defaulting to
+    `request.GET`). Keyword arguments are processed sequentially, with later
+    arguments taking precedence.
 
     For example::
 
+        {# Set a parameter on top of `request.GET` #}
         {% querystring foo=3 %}
 
-    To remove a key::
-
+        {# Remove a key from `request.GET` #}
         {% querystring foo=None %}
 
-    To use with pagination::
-
+        {# Use with pagination #}
         {% querystring page=page_obj.next_page_number %}
 
-    A custom ``QueryDict`` can also be used::
-
+        {# Use a custom ``QueryDict`` #}
         {% querystring my_query_dict foo=3 %}
     """
     if query_dict is None:
diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt
index f5470ad0eb..5712b65d54 100644
--- a/docs/ref/templates/builtins.txt
+++ b/docs/ref/templates/builtins.txt
@@ -996,17 +996,6 @@ Outputs the current query string verbatim. So if the query string is
 Outputs the current query string with the addition of the ``size`` parameter.
 Following the previous example, the output would be ``?color=green&size=M``.
 
-Custom QueryDict
-~~~~~~~~~~~~~~~~
-
-.. code-block:: html+django
-
-    {% querystring my_query_dict %}
-
-You can provide a custom ``QueryDict`` to be used instead of ``request.GET``.
-So if ``my_query_dict`` is ``<QueryDict: {'color': ['blue']}>``, this outputs
-``?color=blue``.
-
 Setting items
 ~~~~~~~~~~~~~
 
@@ -1040,6 +1029,17 @@ Handling lists
 If ``my_list`` is ``["red", "blue"]``, the output will be
 ``?color=red&color=blue``, preserving the list structure in the query string.
 
+Custom QueryDict
+~~~~~~~~~~~~~~~~
+
+.. code-block:: html+django
+
+    {% querystring my_query_dict %}
+
+You can provide a custom ``QueryDict`` to be used instead of ``request.GET``.
+So if ``my_query_dict`` is ``<QueryDict: {'color': ['blue']}>``, this outputs
+``?color=blue``.
+
 Dynamic usage
 ~~~~~~~~~~~~~