Fixed #9475 -- Allowed RelatedManager.add(), create(), etc. for m2m with a through model.

1 files changed, 27 insertions, 8 deletions

diff --git a/docs/ref/models/relations.txt b/docs/ref/models/relations.txt
index 353504a58e..6274506a87 100644
--- a/docs/ref/models/relations.txt
+++ b/docs/ref/models/relations.txt
@@ -36,7 +36,7 @@ Related objects reference
       In this example, the methods below will be available both on
       ``topping.pizza_set`` and on ``pizza.toppings``.
 
-    .. method:: add(*objs, bulk=True)
+    .. method:: add(*objs, bulk=True, through_defaults=None)
 
         Adds the specified model objects to the related object set.
 
@@ -66,7 +66,15 @@ Related objects reference
         Using ``add()`` on a relation that already exists won't duplicate the
         relation, but it will still trigger signals.
 
-    .. method:: create(**kwargs)
+        Use the ``through_defaults`` argument to specify values for the new
+        :ref:`intermediate model <intermediary-manytomany>` instance(s), if
+        needed.
+
+        .. versionchanged:: 2.2
+
+            The ``through_defaults`` argument was added.
+
+    .. method:: create(through_defaults=None, **kwargs)
 
         Creates a new object, saves it and puts it in the related object set.
         Returns the newly created object::
@@ -96,6 +104,14 @@ Related objects reference
         parameter ``blog`` to ``create()``. Django figures out that the new
         ``Entry`` object's ``blog`` field should be set to ``b``.
 
+        Use the ``through_defaults`` argument to specify values for the new
+        :ref:`intermediate model <intermediary-manytomany>` instance, if
+        needed.
+
+        .. versionchanged:: 2.2
+
+            The ``through_defaults`` argument was added.
+
     .. method:: remove(*objs, bulk=True)
 
         Removes the specified model objects from the related object set::
@@ -149,7 +165,7 @@ Related objects reference
         For many-to-many relationships, the ``bulk`` keyword argument doesn't
         exist.
 
-    .. method:: set(objs, bulk=True, clear=False)
+    .. method:: set(objs, bulk=True, clear=False, through_defaults=None)
 
         Replace the set of related objects::
 
@@ -172,6 +188,14 @@ Related objects reference
         race conditions. For instance, new objects may be added to the database
         in between the call to ``clear()`` and the call to ``add()``.
 
+        Use the ``through_defaults`` argument to specify values for the new
+        :ref:`intermediate model <intermediary-manytomany>` instance(s), if
+        needed.
+
+        .. versionchanged:: 2.2
+
+            The ``through_defaults`` argument was added.
+
     .. note::
 
        Note that ``add()``, ``create()``, ``remove()``, ``clear()``, and
@@ -179,11 +203,6 @@ Related objects reference
        related fields. In other words, there is no need to call ``save()``
        on either end of the relationship.
 
-       Also, if you are using :ref:`an intermediate model
-       <intermediary-manytomany>` for a many-to-many relationship, then the
-       ``add()``, ``create()``, ``remove()``, and ``set()`` methods are
-       disabled.
-
        If you use :meth:`~django.db.models.query.QuerySet.prefetch_related`,
        the ``add()``, ``remove()``, ``clear()``, and ``set()`` methods clear
        the prefetched cache.