Refs #30998 -- Doc'd ModelChoiceField/ModelMultipleChoiceField.iterator attributes and ModelChoiceIterator.

1 files changed, 40 insertions, 0 deletions

diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt
index d57722bae0..0a2e13c85d 100644
--- a/docs/ref/forms/fields.txt
+++ b/docs/ref/forms/fields.txt
@@ -1142,6 +1142,10 @@ method::
             super().__init__(*args, **kwargs)
             self.fields['foo_select'].queryset = ...
 
+Both ``ModelChoiceField`` and ``ModelMultipleChoiceField`` have an ``iterator``
+attribute which specifies the class used to iterate over the queryset when
+generating choices.
+
 ``ModelChoiceField``
 --------------------
 
@@ -1222,6 +1226,13 @@ method::
             ...
             </select>
 
+    ``ModelChoiceField`` also has the attribute:
+
+    .. attribute:: iterator
+
+        The iterator class used to generate field choices from ``queryset``. By
+        default, :class:`ModelChoiceIterator`.
+
     The ``__str__()`` 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
@@ -1268,6 +1279,35 @@ method::
 
         Same as :class:`ModelChoiceField.to_field_name`.
 
+    ``ModelMultipleChoiceField`` also has the attribute:
+
+    .. attribute:: iterator
+
+        Same as :class:`ModelChoiceField.iterator`.
+
+``ModelChoiceIterator``
+-----------------------
+
+.. class:: ModelChoiceIterator(field)
+
+    The default class assigned to the ``iterator`` attribute of
+    :class:`ModelChoiceField` and :class:`ModelMultipleChoiceField`. An
+    iterable that yields 2-tuple choices from the queryset.
+
+    A single argument is required:
+
+    .. attribute:: field
+
+        The instance of ``ModelChoiceField`` or ``ModelMultipleChoiceField`` to
+        iterator and yield choice.
+
+    ``ModelChoiceIterator`` has the following method:
+
+    .. method:: __iter__()
+
+        Yield 2-tuple choices in the same format as used by
+        :attr:`ChoiceField.choices`.
+
 Creating custom fields
 ======================