id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
30917	Clarify Formset documentation.	Ken Whitesell	Ken Whitesell	"I believe the documentation for formsets is either misleading or possibly
incorrect.

From the existing documentation at 
https://docs.djangoproject.com/en/2.2/topics/forms/formsets/

{{{
You might want to allow the user to create several articles at once. 
To create a formset out of an ArticleForm you would do:
   
>>> from django.forms import formset_factory
>>> ArticleFormSet = formset_factory(ArticleForm)
   
You now have created a formset named ArticleFormSet.
}}}

It's my understanding that *at this point* you have not yet created a formset.
What you have done is create a formset class, from which you can create
instances of formsets.

It's not until you execute this line:

{{{
>>> formset = ArticleFormSet()
}}}
   
that you have actually created the formset.


By analogy, consider the detail provided for both Models and Forms.
On the page https://docs.djangoproject.com/en/2.2/ref/models/instances/
it is specified that ""To create a new instance of a model, instantiate it like
any other Python class:""

Likewise, with Forms, at https://docs.djangoproject.com/en/2.2/ref/forms/api/
it states: ""To create an unbound Form instance, simply instantiate the class:""

In both these cases, the distinction is made that there's a fundamental 
difference between creating the Model and Form classes, and creating the
instances of those classes.

I believe the same distinction should be made with reference to Formsets,
making it explicitly clear that the formset_factory function creates a
class, and the class needs to be instantiated to create the instances to
be used within a page.
"	Cleanup/optimization	closed	Documentation	dev	Normal	fixed	Formset		Accepted	1	0	0	0	0	0