[1.10.x] Fixed #27299 -- Documented the Widget.use_required_attribute() method.

Thanks Tim Graham for the review and edits.

Backport of c74378b from master

docs/ref/forms/widgets.txt

@@ -287,6 +287,29 @@ foundation for custom widgets.
         an HTML form submission, so it's unknown whether or not the user
         actually submitted a value.
 
+    .. method:: use_required_attribute(initial)
+
+        .. versionadded:: 1.10.1
+
+        Given a form field's ``initial`` value, returns whether or not the
+        widget can be rendered with the ``required`` HTML attribute. Forms use
+        this method along with :attr:`Field.required
+        <django.forms.Field.required>` and :attr:`Form.use_required_attribute
+        <django.forms.Form.use_required_attribute>` to determine whether or not
+        to display the ``required`` attribute for each field.
+
+        By default, returns ``False`` for hidden widgets and ``True``
+        otherwise. Special cases are :class:`~django.forms.ClearableFileInput`,
+        which returns ``False`` when ``initial`` is not set, and
+        :class:`~django.forms.CheckboxSelectMultiple`, which always returns
+        ``False`` because browser validation would require all checkboxes to be
+        checked instead of at least one.
+
+        Override this method in custom widgets that aren't compatible with
+        browser validation. For example, a WSYSIWG text editor widget backed by
+        a hidden ``textarea`` element may want to always return ``False`` to
+        avoid browser validation on the hidden field.
+
 ``MultiWidget``
 ---------------
 

docs/releases/1.10.txt

@@ -858,7 +858,10 @@ Miscellaneous
 * Required form fields now have the ``required`` HTML attribute. Set the
   :attr:`Form.use_required_attribute <django.forms.Form.use_required_attribute>`
   attribute to ``False`` to disable it. You could also add the ``novalidate``
-  attribute to ``<form>`` if you don't want browser validation.
+  attribute to ``<form>`` if you don't want browser validation. To disable
+  the ``required`` attribute on custom widgets, override the
+  :meth:`Widget.use_required_attribute() <django.forms.Widget.use_required_attribute>`
+  method.
 
 * The WSGI handler no longer removes content of responses from ``HEAD``
   requests or responses with a ``status_code`` of 100-199, 204, or 304. Most