Update the Adaptation docs to be more concrete.docs-update

This should help provide better motivating use cases. Examples inspired by https://glyph.twistedmatrix.com/2021/03/interfaces-and-protocols.html

Also some minor typo fixes and updates to comments.

1 files changed, 6 insertions, 3 deletions

diff --git a/src/zope/interface/adapter.py b/src/zope/interface/adapter.py
index 8242b6b..b9836d9 100644
--- a/src/zope/interface/adapter.py
+++ b/src/zope/interface/adapter.py
@@ -234,12 +234,15 @@ class BaseAdapterRegistry(object):
         Remove the item *to_remove* from the (non-``None``, non-empty)
         *existing_leaf_sequence* and return the mutated sequence.
 
-        Subclasses that redefine `_leafSequenceType` should override
-        this method.
-
         If there is more than one item that is equal to *to_remove*
         they must all be removed.
 
+        Subclasses that redefine `_leafSequenceType` should override
+        this method. Note that they can call this method to help
+        in their implementation; this implementation will always
+        return a new tuple constructed by iterating across
+        the *existing_leaf_sequence* and omitting items equal to *to_remove*.
+
         :param existing_leaf_sequence:
            As for `_addValueToLeaf`, probably an instance of
            `_leafSequenceType` but possibly an older type; never `None`.