Add warning to change note about string changes breaking doctests.

Also tweak documentation to DRY for verifyObject/verifyClass.

2 files changed, 35 insertions, 19 deletions

diff --git a/docs/README.rst b/docs/README.rst
index 4e83c4a..d1e58cf 100644
--- a/docs/README.rst
+++ b/docs/README.rst
@@ -2,6 +2,8 @@
 Interfaces
 ==========
 
+.. currentmodule:: zope.interface
+
 Interfaces are objects that specify (document) the external behavior
 of objects that "provide" them.  An interface specifies behavior
 through:
@@ -296,6 +298,7 @@ be used for classes, but in 3.6.0 and higher it can:
 Note that class decorators using the ``@implementer(IFoo)`` syntax are only
 supported in Python 2.6 and later.
 
+.. autofunction:: implementer
 
 Declaring provided interfaces
 -----------------------------
@@ -412,6 +415,8 @@ We can find out what interfaces are directly provided by an object:
   >>> list(zope.interface.directlyProvidedBy(newfoo))
   []
 
+.. autofunction:: provider
+
 Inherited declarations
 ----------------------
 
@@ -466,6 +471,8 @@ be used for this purpose:
   >>> list(zope.interface.implementedBy(C))
   [<InterfaceClass builtins.IFoo>]
 
+.. autofunction:: classImplements
+
 We can use ``classImplementsOnly`` to exclude inherited interfaces:
 
 .. doctest::
@@ -477,6 +484,7 @@ We can use ``classImplementsOnly`` to exclude inherited interfaces:
   >>> list(zope.interface.implementedBy(C))
   [<InterfaceClass builtins.ISpecial>]
 
+.. autofunction:: classImplementsOnly
 
 
 Declaration Objects
@@ -791,7 +799,7 @@ exceptions as its argument:
   ... except Invalid as e:
   ...     str(e)
   '[RangeError(Range(2, 1))]'
-  
+
 And the list will be filled with the individual exceptions:
 
 .. doctest::
diff --git a/docs/verify.rst b/docs/verify.rst
index 364aedb..6f48218 100644
--- a/docs/verify.rst
+++ b/docs/verify.rst
@@ -3,30 +3,16 @@
 =====================================
 
 The ``zope.interface.verify`` module provides functions that test whether a
-given interface is implemented by a class or provided by an object, resp.
-
-
-Verifying classes
-=================
-
-This is covered by unit tests defined in ``zope.interface.tests.test_verify``.
+given interface is implemented by a class or provided by an object.
 
+.. currentmodule:: zope.interface.verify
 
 Verifying objects
 =================
 
-An object provides an interface if
-
-- either its class declares that it implements the interfaces, or the object
-  declares that it directly provides the interface;
-
-- the object defines all the methods required by the interface;
-
-- all the methods have the correct signature;
-
-- the object defines all non-method attributes required by the interface.
+.. autofunction:: verifyObject
 
-This doctest currently covers only the latter item.
+.. autoexception:: zope.interface.Invalid
 
 Testing for attributes
 ----------------------
@@ -208,3 +194,25 @@ variable keyword arguments, the implementation must also accept them.
    ...     def needs_varargs(self, **kwargs): pass
    >>> verify_foo()
    The object <Foo...> violates its contract in IFoo.needs_varargs(*args): implementation doesn't support variable arguments.
+
+Verifying Classes
+=================
+
+The function `verifyClass` is used to check that a class implements
+an interface properly, meaning that its instances properly provide the
+interface. Most of the same things that `verifyObject` checks can be
+checked for classes.
+
+.. autofunction:: verifyClass
+
+.. doctest::
+
+    >>> from zope.interface.verify import verifyClass
+    >>> def verify_foo_class():
+    ...    try:
+    ...        return verifyClass(IFoo, Foo)
+    ...    except BrokenMethodImplementation as e:
+    ...        print(e)
+
+    >>> verify_foo_class()
+    The object <class 'Foo'> violates its contract in IFoo.needs_varargs(*args): implementation doesn't support variable arguments.