Ticket #10361: 10361.diff

docs/ref/forms/fields.txt

@@ -680 +680 @@
 
 Takes the following optional arguments:
 
-
 .. attribute:: URLField.max_length
 .. attribute:: URLField.min_length
 
@@ -699 +698 @@
 Slightly complex built-in ``Field`` classes
 -------------------------------------------
 
-The following are not yet documented.
-
 .. class:: ComboField(**kwargs)
 
+    * Default widget: ``TextInput``
+    * Empty value: ``''`` (an empty string)
+    * Normalizes to: A Unicode object.
+    * Validates that the given value against each of the fields specified
+      as an argument to the ``ComboField``.
+    * Error message keys: ``required``, ``invalid``
+
+Takes one extra required argument:
+
+.. attribute:: ComboField.fields
+
+The list of fields that should be used to validate the field's value (in the
+order in which they are provided).
+    
+    >>> f = ComboField(fields=[CharField(max_length=20), EmailField()])
+    >>> f.clean('test@example.com')
+    u'test@example.com'
+    >>> f.clean('longemailaddress@example.com')
+    Traceback (most recent call last):
+    ...
+    ValidationError: [u'Ensure this value has at most 20 characters (it has 28).']
+
 .. class:: MultiValueField(**kwargs)
 
+    * Default widget: ``TextInput``
+    * Empty value: ``''`` (an empty string)
+    * Normalizes to: the type returned by the ``compress`` method of the subclass.
+    * Validates that the given value against each of the fields specified
+      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.
+
+Takes one extra required argument:
+
+.. attribute:: MultiValueField.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 thesecond field, etc.
+Once all fields are cleaned, the list of clean values is"compressed" into a
+single value.
+
 .. class:: SplitDateTimeField(**kwargs)
 
     * Default widget: ``SplitDateTimeWidget``