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

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``

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()