Fixed #28514 -- Clarifed docs about idempotence of RelatedManager.add().

2 files changed, 8 insertions, 4 deletions

diff --git a/docs/ref/models/relations.txt b/docs/ref/models/relations.txt
index beffe1283e..9814485445 100644
--- a/docs/ref/models/relations.txt
+++ b/docs/ref/models/relations.txt
@@ -56,11 +56,15 @@ Related objects reference
         manager perform the update by calling ``e.save()``.
 
         Using ``add()`` with a many-to-many relationship, however, will not
-        call any ``save()`` methods, but rather create the relationships
-        using :meth:`QuerySet.bulk_create()
+        call any ``save()`` methods (the ``bulk`` argument doesn't exist), but
+        rather create the relationships using :meth:`QuerySet.bulk_create()
         <django.db.models.query.QuerySet.bulk_create>`. If you need to execute
         some custom logic when a relationship is created, listen to the
-        :data:`~django.db.models.signals.m2m_changed` signal.
+        :data:`~django.db.models.signals.m2m_changed` signal, which will
+        trigger ``pre_add`` and ``post_add`` actions.
+
+        Using ``add()`` on a relation that already exists won't duplicate the
+        relation, but it will still trigger signals.
 
     .. method:: create(**kwargs)
 
diff --git a/docs/topics/db/examples/many_to_many.txt b/docs/topics/db/examples/many_to_many.txt
index 7173faaeca..065ab1605b 100644
--- a/docs/topics/db/examples/many_to_many.txt
+++ b/docs/topics/db/examples/many_to_many.txt
@@ -75,7 +75,7 @@ Create another ``Article``, and set it to appear in both ``Publications``::
     >>> a2.publications.add(p1, p2)
     >>> a2.publications.add(p3)
 
-Adding a second time is OK::
+Adding a second time is OK, it will not duplicate the relation::
 
     >>> a2.publications.add(p3)