Fixed #26678 -- Doc'd that RelatedManager.add()/remove()/set() accepts the field…

Fixed #26678 -- Doc'd that RelatedManager.add()/remove()/set() accepts the field the relation points to.

django/db/models/fields/related_descriptors.py

@@ -1148,7 +1148,8 @@ def create_forward_many_to_many_manager(superclass, rel, reverse):
         def _remove_items(self, source_field_name, target_field_name, *objs):
             # source_field_name: the PK colname in join table for the source object
             # target_field_name: the PK colname in join table for the target object
-            # *objs - objects to remove
+            # *objs - objects to remove. Either object instances, or primary
+            # keys of object instances.
             if not objs:
                 return
 

docs/ref/models/relations.txt

@@ -66,6 +66,9 @@ Related objects reference
         Using ``add()`` on a relation that already exists won't duplicate the
         relation, but it will still trigger signals.
 
+        ``add()`` also accepts the field the relation points to as an argument.
+        The above example can be rewritten as ``b.entry_set.add(234)``.
+
         Use the ``through_defaults`` argument to specify values for the new
         :ref:`intermediate model <intermediary-manytomany>` instance(s), if
         needed.
@@ -128,6 +131,10 @@ Related objects reference
         :data:`~django.db.models.signals.m2m_changed` signal if you wish to
         execute custom code when a relationship is deleted.
 
+        Similarly to :meth:`add()`, ``remove()`` also accepts the field the
+        relation points to as an argument. The above example can be rewritten
+        as ``b.entry_set.remove(234)``.
+
         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
@@ -188,6 +195,10 @@ 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()``.
 
+        Similarly to :meth:`add()`, ``set()`` also accepts the field the
+        relation points to as an argument. The above example can be rewritten
+        as ``e.related_set.set([obj1.pk, obj2.pk, obj3.pk])``.
+
         Use the ``through_defaults`` argument to specify values for the new
         :ref:`intermediate model <intermediary-manytomany>` instance(s), if
         needed.