From acf0ff02e78105c67d2a66c7c898f572ae84fdc0 Mon Sep 17 00:00:00 2001
From: Adrian Holovaty <adrian@holovaty.com>
Date: Sun, 1 Jul 2007 04:24:20 +0000
Subject: [PATCH] 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/fields.py  | 13 +++++++------
 django/newforms/widgets.py | 34 +++++++++++++++++++++++++---------
 2 files changed, 32 insertions(+), 15 deletions(-)

diff --git a/django/newforms/fields.py b/django/newforms/fields.py
index 167281a0611..cec2ae8317c 100644
--- a/django/newforms/fields.py
+++ b/django/newforms/fields.py
@@ -482,17 +482,18 @@ class ComboField(Field):
 
 class MultiValueField(Field):
     """
-    A Field that is composed of multiple Fields.
-
-    Its clean() method takes a "decompressed" list of values. Each value in
+    A Field that aggregates the logic of multiple Fields.
+    
+    Its clean() method takes a "decompressed" list of values, which are then
+    cleaned into a single value according to self.fields. Each value in
     this list is cleaned by the corresponding field -- 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.
 
-    Subclasses should implement compress(), which specifies how a list of
-    valid values should be converted to a single value. Subclasses should not
-    have to implement clean().
+    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.
 
     You'll probably want to use this with MultiWidget.
     """
diff --git a/django/newforms/widgets.py b/django/newforms/widgets.py
index d4b5f596d14..ecd6dcc9d38 100644
--- a/django/newforms/widgets.py
+++ b/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):