From 9be36f8044c3bdfe5d1819d4b3b62bee64a039e3 Mon Sep 17 00:00:00 2001
From: David Smith <smithdc@gmail.com>
Date: Sat, 2 Oct 2021 07:14:51 +0100
Subject: [PATCH] Refs #31026 -- Improved BoundField.label_tag() docs.

---
 docs/ref/forms/api.txt | 38 +++++++++++++++++++++++++++-----------
 1 file changed, 27 insertions(+), 11 deletions(-)

diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt
index 9dcfbcfb09c..d80d9ea2242 100644
--- a/docs/ref/forms/api.txt
+++ b/docs/ref/forms/api.txt
@@ -1210,6 +1210,29 @@ Methods of ``BoundField``
 
 .. method:: BoundField.label_tag(contents=None, attrs=None, label_suffix=None)
 
+    Renders a label tag for the form field using the template specified by
+    :attr:`.Form.template_name_label`.
+
+    The available context is:
+
+    * ``field``: This instance of the :class:`BoundField`.
+    * ``contents``: By default a concatenated string of
+      :attr:`BoundField.label` and :attr:`Form.label_suffix` (or
+      :attr:`Field.label_suffix`, if set). This can be overridden by the
+      ``contents`` and ``label_suffix`` arguments.
+    * ``attrs``: A ``dict`` containing ``for``,
+      :attr:`Form.required_css_class`, and ``id``. ``id`` is generated by the
+      field's widget ``attrs`` or :attr:`BoundField.auto_id`. Additional
+      attributes can be provided by the ``attrs`` argument.
+    * ``use_tag``: A boolean which is ``True`` if the label has an ``id``.
+      If ``False`` the default template omits the ``<label>`` tag.
+
+    .. tip::
+
+        In your template ``field`` is the instance of the ``BoundField``.
+        Therefore ``field.field`` accesses :attr:`BoundField.field` being
+        the field you declare, e.g. ``forms.CharField``.
+
     To separately render the label tag of a form field, you can call its
     ``label_tag()`` method::
 
@@ -1217,17 +1240,10 @@ Methods of ``BoundField``
         >>> print(f['message'].label_tag())
         <label for="id_message">Message:</label>
 
-    You can provide the ``contents`` parameter which will replace the
-    auto-generated label tag. An ``attrs`` dictionary may contain additional
-    attributes for the ``<label>`` tag.
-
-    The HTML that's generated includes the form's
-    :attr:`~django.forms.Form.label_suffix` (a colon, by default) or, if set,
-    the current field's :attr:`~django.forms.Field.label_suffix`. The optional
-    ``label_suffix`` parameter allows you to override any previously set
-    suffix. For example, you can use an empty string to hide the label on
-    selected fields. The label is rendered using the template specified by the
-    forms :attr:`.Form.template_name_label`.
+    If you'd like to customize the rendering this can be achieved by overriding
+    the :attr:`.Form.template_name_label` attribute or more generally by
+    overriding the default template, see also
+    :ref:`overriding-built-in-form-templates`.
 
     .. versionchanged:: 4.0