From 5da85ea73724d75e609c5ee4316e7e5be8f17810 Mon Sep 17 00:00:00 2001
From: Jon Dufresne <jon.dufresne@gmail.com>
Date: Sun, 24 Nov 2019 09:37:38 -0800
Subject: [PATCH] Refs #30998 -- Doc'd
 ModelChoiceField/ModelMultipleChoiceField.iterator attributes and
 ModelChoiceIterator.

---
 docs/ref/forms/fields.txt | 40 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt
index d57722bae0d..0a2e13c85db 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
 ======================