Added some clearer docstrings to MultiValueField and MultiWidget

git-svn-id: http://code.djangoproject.com/svn/django/trunk@5575 bcc190cf-cafb-0310-a4f2-bffc1f526a37

django/newforms/widgets.py

@@ -304,19 +304,28 @@ class MultiWidget(Widget):
     """
     A widget that is composed of multiple widgets.
 
-    Its render() method takes a "decompressed" list of values, not a single
-    value. Each value in this list is rendered in the corresponding widget --
-    the first value is rendered in the first widget, the second value is
-    rendered in the second widget, etc.
+    Its render() method is different than other widgets', because it has to
+    figure out how to split a single value for display in multiple widgets.
+    The ``value`` argument can be one of two things:
 
-    Subclasses should implement decompress(), which specifies how a single
-    value should be converted to a list of values. Subclasses should not
-    have to implement clean().
+        * A list.
+        * A normal value (e.g., a string) that has been "compressed" from
+          a list of values.
+
+    In the second case -- i.e., if the value is NOT a list -- render() will
+    first "decompress" the value into a list before rendering it. It does so by
+    calling the decompress() method, which MultiWidget subclasses must
+    implement. This method takes a single "compressed" value and returns a
+    list.
+
+    When render() does its HTML rendering, each value in the list is rendered
+    with the corresponding widget -- the first value is rendered in the first
+    widget, the second value is rendered in the second widget, etc.
 
     Subclasses may implement format_output(), which takes the list of rendered
-    widgets and returns HTML that formats them any way you'd like.
+    widgets and returns a string of HTML that formats them any way you'd like.
 
-    You'll probably want to use this with MultiValueField.
+    You'll probably want to use this class with MultiValueField.
     """
     def __init__(self, widgets, attrs=None):
         self.widgets = [isinstance(w, type) and w() or w for w in widgets]
@@ -351,6 +360,13 @@ class MultiWidget(Widget):
         return [widget.value_from_datadict(data, name + '_%s' % i) for i, widget in enumerate(self.widgets)]
 
     def format_output(self, rendered_widgets):
+        """
+        Given a list of rendered widgets (as strings), returns a Unicode string
+        representing the HTML for the whole lot.
+
+        This hook allows you to format the HTML design of the widgets, if
+        needed.
+        """
         return u''.join(rendered_widgets)
 
     def decompress(self, value):