queryset-refactor: Merged from trunk up to [6953].

git-svn-id: http://code.djangoproject.com/svn/django/branches/queryset-refactor@6954 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 18 insertions, 15 deletions

diff --git a/docs/modelforms.txt b/docs/modelforms.txt
index 8580fe1dbd..0136540bed 100644
--- a/docs/modelforms.txt
+++ b/docs/modelforms.txt
@@ -24,12 +24,11 @@ For example::
     ...         model = Article
 
     # Creating a form to add an article.
-    >>> article = Article()
-    >>> form = ArticleForm(article)
+    >>> form = ArticleForm()
 
     # Creating a form to change an existing article.
     >>> article = Article.objects.get(pk=1)
-    >>> form = ArticleForm(article)
+    >>> form = ArticleForm(instance=article)
 
 Field types
 -----------
@@ -166,18 +165,23 @@ we'll discuss in a moment.)::
 The ``save()`` method
 ---------------------
 
-Every form produced by ``ModelForm`` also has a ``save()`` method. This
-method creates and saves a database object from the data bound to the form.
-A subclass of ``ModelForm`` also requires a model instance as the first
-arument to its constructor. For example::
+Every form produced by ``ModelForm`` also has a ``save()``
+method. This method creates and saves a database object from the data
+bound to the form. A subclass of ``ModelForm`` can accept an existing
+model instance as the keyword argument ``instance``; if this is
+supplied, ``save()`` will update that instance. If it's not supplied,
+``save()`` will create a new instance of the specified model::
 
     # Create a form instance from POST data.
-    >>> a = Article()
-    >>> f = ArticleForm(a, request.POST)
+    >>> f = ArticleForm(request.POST)
 
     # Save a new Article object from the form's data.
     >>> new_article = f.save()
 
+    # Create a form to edit an existing Article.
+    >>> a = Article.objects.get(pk=1)
+    >>> f = ArticleForm(instance=a)
+
 Note that ``save()`` will raise a ``ValueError`` if the data in the form
 doesn't validate -- i.e., ``if form.errors``.
 
@@ -201,8 +205,7 @@ you've manually saved the instance produced by the form, you can invoke
 ``save_m2m()`` to save the many-to-many form data. For example::
 
     # Create a form instance with POST data.
-    >>> a = Author()
-    >>> f = AuthorForm(a, request.POST)
+    >>> f = AuthorForm(request.POST)
 
     # Create, but don't save the new author instance.
     >>> new_author = f.save(commit=False)
@@ -274,10 +277,10 @@ model fields:
     any attempt to ``save()`` a ``ModelForm`` with missing fields will fail.
     To avoid this failure, you must instantiate your model with initial values
     for the missing, but required fields, or use ``save(commit=False)`` and
-    manually set anyextra required fields::
+    manually set any extra required fields::
     
-        instance = Instance(requiured_field='value')
-        form = InstanceForm(instance, request.POST)
+        instance = Instance(required_field='value')
+        form = InstanceForm(request.POST, instance=instance)
         new_instance = form.save()
 
         instance = form.save(commit=False)
@@ -293,7 +296,7 @@ Overriding the default field types
 ----------------------------------
 
 The default field types, as described in the "Field types" table above, are
-sensible defaults; if you have a ``DateField`` in your model, chances are you'd
+sensible defaults. If you have a ``DateField`` in your model, chances are you'd
 want that to be represented as a ``DateField`` in your form. But
 ``ModelForm`` gives you the flexibility of changing the form field type
 for a given model field. You do this by declaratively specifying fields like