[2.2.x] Fixed #27462 -- Clarifed pk_set difference in m2m_changed signal receivers for add() and remove().

Thank you to Mariusz Felisiak for review.

Backport of bae05bcf68710cb6dafa51325c3ec83ddda83c39 from master

1 files changed, 10 insertions, 3 deletions

diff --git a/docs/ref/signals.txt b/docs/ref/signals.txt
index 19a92a875c..48915cdc45 100644
--- a/docs/ref/signals.txt
+++ b/docs/ref/signals.txt
@@ -270,9 +270,16 @@ Arguments sent with this signal:
     from the relation.
 
 ``pk_set``
-    For the ``pre_add``, ``post_add``, ``pre_remove`` and ``post_remove``
-    actions, this is a set of primary key values that have been added to
-    or removed from the relation.
+    For the ``pre_add`` and ``post_add`` actions, this is a set of primary key
+    values that will be, or have been, added to the relation. This may be a
+    subset of the values submitted to be added, since inserts must filter
+    existing values in order to avoid a database ``IntegrityError``.
+
+    For the ``pre_remove`` and ``post_remove`` actions, this is a set of
+    primary key values that was submitted to be removed from the relation. This
+    is not dependent on whether the values actually will be, or have been,
+    removed. In particular, non-existent values may be submitted, and will
+    appear in ``pk_set``, even though they have no effect on the database.
 
     For the ``pre_clear`` and ``post_clear`` actions, this is ``None``.