Ticket #17528: 17528.diff

docs/ref/models/relations.txt

@@ -48 +48 @@
             >>> e = Entry.objects.get(id=234)
             >>> b.entry_set.add(e) # Associates Entry e with Blog b.
 
+        In the example above, ``e.save()`` is called to perform the update.
+        Using ``add()`` with a many-to-many relationship, however, will not
+        call any ``save()`` methods, but rather fire the
+        :data:`~django.db.models.signals.m2m_changed` signal. The relationships
+        are created using :meth:`QuerySet.bulk_create
+        <django.db.models.query.QuerySet.bulk_create>`.
+
     .. method:: create(**kwargs)
 
         Creates a new object, saves it and puts it in the related object set.
@@ -86 +93 @@
             >>> e = Entry.objects.get(id=234)
             >>> b.entry_set.remove(e) # Disassociates Entry e from Blog b.
 
+        Similar to :meth:`add()`, ``e.save()`` would be called in the example
+        above to perform the update. Using ``remove()`` with a many-to-many
+        relationship, however, will delete the relationships using
+        :meth:`QuerySet.delete<django.db.models.query.QuerySet.delete>` which
+        means no model ``save()`` methods are called; rather the
+        :data:`~django.db.models.signals.m2m_changed` signal will be fired.
+
         For :class:`~django.db.models.ForeignKey` objects, this method only
         exists if ``null=True``. If the related field can't be set to ``None``
         (``NULL``), then an object can't be removed from a relation without