[1.1.X] Fixed #12097 -- Cleaned up the documentation for ModelChoiceField and MultipleModelChoiceField. Thanks to JasonYosinski for the patch.

Backport of r12712 from trunk.

git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.1.X@12715 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 35 insertions, 24 deletions

diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt
index 94e9ba349a..f607fdd8e9 100644
--- a/docs/ref/forms/fields.txt
+++ b/docs/ref/forms/fields.txt
@@ -755,15 +755,22 @@ for ``TimeField`` are used.
 Fields which handle relationships
 ---------------------------------
 
-For representing relationships between models, two fields are
-provided which can derive their choices from a ``QuerySet``:
+Two fields are available for representing relationships between
+models: :class:`ModelChoiceField` and
+:class:`ModelMultipleChoiceField`.  Both of these fields require a
+single ``queryset`` parameter that is used to create the choices for
+the field.  Upon form validation, these fields will place either one
+model object (in the case of ``ModelChoiceField``) or multiple model
+objects (in the case of ``ModelMultipleChoiceField``) into the
+``cleaned_data`` dictionary of the form.
+
+``ModelChoiceField``
+~~~~~~~~~~~~~~~~~~~~
 
 .. class:: ModelChoiceField(**kwargs)
-.. class:: ModelMultipleChoiceField(**kwargs)
 
-These fields place one or more model objects into the ``cleaned_data``
-dictionary of forms in which they're used. Both of these fields have an
-additional required argument:
+Allows the selection of a single model object, suitable for
+representing a foreign key.  A single argument is required:
 
 .. attribute:: ModelChoiceField.queryset
 
@@ -771,22 +778,7 @@ additional required argument:
     field will be derived, and which will be used to validate the
     user's selection.
 
-``ModelChoiceField``
-~~~~~~~~~~~~~~~~~~~~
-
-Allows the selection of a single model object, suitable for
-representing a foreign key.
-
-The ``__unicode__`` method of the model will be called to generate
-string representations of the objects for use in the field's choices;
-to provide customized representations, subclass ``ModelChoiceField``
-and override ``label_from_instance``. This method will receive a model
-object, and should return a string suitable for representing it. For
-example::
-
-    class MyModelChoiceField(ModelChoiceField):
-        def label_from_instance(self, obj):
-            return "My Object #%i" % obj.id
+``ModelChoiceField`` also takes one optional argument:
 
 .. attribute:: ModelChoiceField.empty_label
 
@@ -806,13 +798,32 @@ example::
    initial value, no empty choice is created (regardless of the value
    of ``empty_label``).
 
+The ``__unicode__`` method of the model will be called to generate
+string representations of the objects for use in the field's choices;
+to provide customized representations, subclass ``ModelChoiceField``
+and override ``label_from_instance``. This method will receive a model
+object, and should return a string suitable for representing it. For
+example::
+
+    class MyModelChoiceField(ModelChoiceField):
+        def label_from_instance(self, obj):
+            return "My Object #%i" % obj.id
+
 ``ModelMultipleChoiceField``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. class:: ModelMultipleChoiceField(**kwargs)
+
 Allows the selection of one or more model objects, suitable for
-representing a many-to-many relation. As with ``ModelChoiceField``,
+representing a many-to-many relation. As with :class:`ModelChoiceField`,
 you can use ``label_from_instance`` to customize the object
-representations.
+representations, and ``queryset`` is a required parameter:
+
+.. attribute:: ModelMultipleChoiceField.queryset
+
+    A ``QuerySet`` of model objects from which the choices for the
+    field will be derived, and which will be used to validate the
+    user's selection.
 
 Creating custom fields
 ----------------------