[1.4.x] Fixed #11185 - Expanded docs on customizing widgets; thanks fadeev for the draft patch.

Backport of a73838fde33374573b8e765dfcb0225287d396c0 from master.

1 files changed, 29 insertions, 12 deletions

diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt
index d83f781dc7..7ebd495924 100644
--- a/docs/ref/forms/fields.txt
+++ b/docs/ref/forms/fields.txt
@@ -861,7 +861,7 @@ Slightly complex built-in ``Field`` classes
 ``MultiValueField``
 ~~~~~~~~~~~~~~~~~~~
 
-.. class:: MultiValueField(**kwargs)
+.. class:: MultiValueField(fields=(), **kwargs)
 
     * Default widget: ``TextInput``
     * Empty value: ``''`` (an empty string)
@@ -870,22 +870,39 @@ Slightly complex built-in ``Field`` classes
       as an argument to the ``MultiValueField``.
     * Error message keys: ``required``, ``invalid``
 
-    This abstract field (must be subclassed) aggregates the logic of multiple
-    fields. Subclasses should not have to implement clean(). Instead, they must
-    implement compress(), which takes a list of valid values and returns a
-    "compressed" version of those values -- a single value.  For example,
-    :class:`SplitDateTimeField` is a subclass which combines a time field and
-    a date field into a datetime object.
+    Aggregates the logic of multiple fields that together produce a single
+    value.
+
+    This field is abstract and must be subclassed. In contrast with the
+    single-value fields, subclasses of :class:`MultiValueField` must not
+    implement :meth:`~django.forms.Field.clean` but instead - implement
+    :meth:`~MultiValueField.compress`.
 
     Takes one extra required argument:
 
     .. attribute:: fields
 
-        A list of fields which are cleaned into a single field. Each value in
-        ``clean`` is cleaned by the corresponding field in ``fields`` -- the first
-        value is cleaned by the first field, the second value is cleaned by
-        the second field, etc.  Once all fields are cleaned, the list of clean
-        values is "compressed" into a single value.
+        A tuple of fields whose values are cleaned and subsequently combined
+        into a single value.  Each value of the field is cleaned by the
+        corresponding field in ``fields`` -- the first value is cleaned by the
+        first field, the second value is cleaned by the second field, etc.
+        Once all fields are cleaned, the list of clean values is combined into
+        a single value by :meth:`~MultiValueField.compress`.
+
+    .. attribute:: MultiValueField.widget
+
+        Must be a subclass of :class:`django.forms.MultiWidget`.
+        Default value is :class:`~django.forms.widgets.TextInput`, which
+        probably is not very useful in this case.
+
+    .. method:: compress(data_list)
+
+        Takes a list of valid values and returns  a "compressed" version of
+        those values -- in a single value. For example,
+        :class:`SplitDateTimeField` is a subclass which combines a time field
+        and a date field into a ``datetime`` object.
+
+        This method must be implemented in the subclasses.
 
 ``SplitDateTimeField``
 ~~~~~~~~~~~~~~~~~~~~~~