[1.6.x] Fixed #20999 - Allow overriding formfield class with choices, without subclass restrictions.

Refs #18162. Thanks claudep and mjtamlyn for review.

Backport of 7211741fc5d50425 from master.

1 files changed, 13 insertions, 7 deletions

diff --git a/docs/howto/custom-model-fields.txt b/docs/howto/custom-model-fields.txt
index af652de78c..7abecefb8b 100644
--- a/docs/howto/custom-model-fields.txt
+++ b/docs/howto/custom-model-fields.txt
@@ -617,17 +617,23 @@ prepared with :meth:`.get_prep_lookup`.
 Specifying the form field for a model field
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. method:: Field.formfield(self, form_class=forms.CharField, **kwargs)
+.. method:: Field.formfield(self, form_class=None, choices_form_class=None, **kwargs)
 
-Returns the default form field to use when this field is displayed in a model.
-This method is called by the :class:`~django.forms.ModelForm` helper.
+Returns the default form field to use when this model field is displayed in a
+form.  This method is called by the :class:`~django.forms.ModelForm` helper.
+
+The form field class can be specified via the ``form_class`` and
+``choices_form_class`` arguments; the latter is used if the field has choices
+specified, the former otherwise. If these arguments are not provided,
+:class:`~django.forms.CharField` or :class:`~django.forms.TypedChoiceField`
+will be used.
 
 All of the ``kwargs`` dictionary is passed directly to the form field's
 ``__init__()`` method. Normally, all you need to do is set up a good default
-for the ``form_class`` argument and then delegate further handling to the
-parent class. This might require you to write a custom form field (and even a
-form widget). See the :doc:`forms documentation </topics/forms/index>` for
-information about this.
+for the ``form_class`` (and maybe ``choices_form_class``) argument and then
+delegate further handling to the parent class. This might require you to write
+a custom form field (and even a form widget). See the :doc:`forms documentation
+</topics/forms/index>` for information about this.
 
 Continuing our ongoing example, we can write the :meth:`.formfield` method as::