Fixed #25672 -- Clarified why related ManyToManyFields with a custom…

Fixed #25672 -- Clarified why related ManyToManyFields with a custom intermediate model disable the remove() method.

docs/topics/db/models.txt

@@ -513,11 +513,11 @@ the intermediate model::
 Unlike normal many-to-many fields, you *can't* use ``add()``, ``create()``,
 or ``set()`` to create relationships::
 
-    # THIS WILL NOT WORK
+    >>> # THIS WILL NOT WORK
     >>> beatles.members.add(john)
-    # NEITHER WILL THIS
+    >>> # NEITHER WILL THIS
     >>> beatles.members.create(name="George Harrison")
-    # AND NEITHER WILL THIS
+    >>> # AND NEITHER WILL THIS
     >>> beatles.members.set([john, paul, ringo, george])
 
 Why? You can't just create a relationship between a ``Person`` and a ``Group``
@@ -529,9 +529,21 @@ The only way to create this type of relationship is to create instances of the
 intermediate model.
 
 The :meth:`~django.db.models.fields.related.RelatedManager.remove` method is
-disabled for similar reasons. However, the
-:meth:`~django.db.models.fields.related.RelatedManager.clear` method can be
-used to remove all many-to-many relationships for an instance::
+disabled for similar reasons. For example, if the custom through table defined
+by the intermediate model does not enforce uniqueness on the
+``(model1, model2)`` pair, a ``remove()`` call would not provide enough
+information as to which intermediate model instance should be deleted::
+
+    >>> Membership.objects.create(person=ringo, group=beatles,
+    ...     date_joined=date(1968, 9, 4),
+    ...     invite_reason="You've been gone for a month and we miss you.")
+    >>> beatles.members.all()
+    <QuerySet [<Person: Ringo Starr>, <Person: Paul McCartney>, <Person: Ringo Starr>]>
+    >>> # THIS WILL NOT WORK BECAUSE IT CANNOT TELL WHICH MEMBERSHIP TO REMOVE
+    >>> beatles.members.remove(ringo)
+
+However, the :meth:`~django.db.models.fields.related.RelatedManager.clear`
+method can be used to remove all many-to-many relationships for an instance::
 
     >>> # Beatles have broken up
     >>> beatles.members.clear()