Add warning to change note about string changes breaking doctests.

Also tweak documentation to DRY for verifyObject/verifyClass.

2 files changed, 31 insertions, 7 deletions

diff --git a/src/zope/interface/interfaces.py b/src/zope/interface/interfaces.py
index 6d98591..6ac235a 100644
--- a/src/zope/interface/interfaces.py
+++ b/src/zope/interface/interfaces.py
@@ -580,6 +580,10 @@ class IInterfaceDeclaration(Interface):
 
         Instances of ``C`` implement ``I1``, ``I2``, and whatever interfaces
         instances of ``A`` and ``B`` implement.
+
+        .. deprecated:: 5.0
+           This only works for Python 2. The `implementer` decorator
+           is preferred for all versions.
         """
 
     def implementsOnly(*interfaces):
@@ -612,6 +616,10 @@ class IInterfaceDeclaration(Interface):
 
         Instances of ``C`` implement ``I1``, ``I2``, regardless of what
         instances of ``A`` and ``B`` implement.
+
+        .. deprecated:: 5.0
+           This only works for Python 2. The `implementer_only` decorator
+           is preferred for all versions.
         """
 
     def classProvides(*interfaces):
@@ -642,7 +650,12 @@ class IInterfaceDeclaration(Interface):
           directlyProvides(theclass, I1)
 
         after the class has been created.
+
+        .. deprecated:: 5.0
+           This only works for Python 2. The `provider` decorator
+           is preferred for all versions.
         """
+
     def provider(*interfaces):
         """A class decorator version of `classProvides`"""
 
diff --git a/src/zope/interface/verify.py b/src/zope/interface/verify.py
index 40c0fb1..a8dd952 100644
--- a/src/zope/interface/verify.py
+++ b/src/zope/interface/verify.py
@@ -36,20 +36,27 @@ MethodTypes = (MethodType, )
 
 
 def _verify(iface, candidate, tentative=False, vtype=None):
-    """Verify that *candidate* might correctly implement *iface*.
+    """
+    Verify that *candidate* might correctly provide *iface*.
 
     This involves:
 
-      - Making sure the candidate defines all the necessary methods
+    - Making sure the candidate claims that it provides the
+      interface using ``iface.providedBy`` (unless *tentative* is `True`,
+      in which case this step is skipped). This means that the candidate's class
+      declares that it `implements <zope.interface.implementer>` the interface,
+      or the candidate itself declares that it `provides <zope.interface.provider>`
+      the interface
 
-      - Making sure the methods have the correct signature
+    - Making sure the candidate defines all the necessary methods
 
-      - Making sure the candidate asserts that it implements the interface
+    - Making sure the methods have the correct signature (to the
+      extent possible)
 
-    Note that this isn't the same as verifying that the class does
-    implement the interface.
+    - Making sure the candidate defines all the necessary attributes
 
-    If  *tentative* is true (not the default), suppress the "is implemented by" test.
+    :raises zope.interface.Invalid: If any of the previous
+       conditions does not hold.
     """
 
     if vtype == 'c':
@@ -126,11 +133,15 @@ def _verify(iface, candidate, tentative=False, vtype=None):
     return True
 
 def verifyClass(iface, candidate, tentative=False):
+    """
+    Verify that the *candidate* might correctly provide *iface*.
+    """
     return _verify(iface, candidate, tentative, vtype='c')
 
 def verifyObject(iface, candidate, tentative=False):
     return _verify(iface, candidate, tentative, vtype='o')
 
+verifyObject.__doc__ = _verify.__doc__
 
 _MSG_TOO_MANY = 'implementation requires too many arguments'
 _KNOWN_PYPY2_FALSE_POSITIVES = frozenset((