Update documentation and Provides repr for better debugging.

Fixes #229.

Replaces #232

4 files changed, 37 insertions, 3 deletions

diff --git a/CHANGES.rst b/CHANGES.rst
index c791f50..02d72c2 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -5,6 +5,10 @@
 5.3.0 (unreleased)
 ==================
 
+- Improve the repr of ``zope.interface.Provides`` to remove ambiguity
+  about what is being provided. This is especially helpful diagnosing
+  IRO issues.
+
 - Allow subclasses of ``BaseAdapterRegistry`` (including
   ``AdapterRegistry`` and ``VerifyingAdapterRegistry``) to have
   control over the data structures. This allows persistent
diff --git a/src/zope/interface/declarations.py b/src/zope/interface/declarations.py
index ec67eee..45d2998 100644
--- a/src/zope/interface/declarations.py
+++ b/src/zope/interface/declarations.py
@@ -763,10 +763,11 @@ class Provides(Declaration):  # Really named ProvidesClass
         Declaration.__init__(self, *self._add_interfaces_to_cls(interfaces, cls))
 
     def __repr__(self):
-        return "<%s.%s for %s>" % (
+        return "<%s.%s for instances of %s providing %s>" % (
             self.__class__.__module__,
             self.__class__.__name__,
             self._cls,
+            self.__args[1:],
         )
 
     def __reduce__(self):
diff --git a/src/zope/interface/ro.py b/src/zope/interface/ro.py
index 20338ed..89dde67 100644
--- a/src/zope/interface/ro.py
+++ b/src/zope/interface/ro.py
@@ -45,6 +45,10 @@ ZOPE_INTERFACE_STRICT_IRO
     If this is set to "1", any attempt to use :func:`ro` that would produce a non-C3
     ordering will fail by raising :class:`InconsistentResolutionOrderError`.
 
+.. important::
+
+   ``ZOPE_INTERFACE_STRICT_IRO`` is intended to become the default in the future.
+
 There are two environment variables that are independent.
 
 ZOPE_INTERFACE_LOG_CHANGED_IRO
@@ -56,6 +60,25 @@ ZOPE_INTERFACE_USE_LEGACY_IRO
     legacy IRO will be used instead. This is a temporary measure and will be removed in the
     future. It is intended to help during the transition.
     It implies ``ZOPE_INTERFACE_LOG_CHANGED_IRO``.
+
+.. rubric:: Debugging Behaviour Changes in zope.interface 5
+
+Most behaviour changes from zope.interface 4 to 5 are related to
+inconsistent resolution orders. ``ZOPE_INTERFACE_STRICT_IRO`` is the
+most effective tool to find such inconsistent resolution orders, and
+we recommend running your code with this variable set if at all
+possible. Doing so will ensure that all interface resolution orders
+are consistent, and if they're not, will immediately point the way to
+where this is violated.
+
+Occasionally, however, this may not be enough. This is because in some
+cases, a C3 ordering can be found (the resolution order is fully
+consistent) that is substantially different from the ad-hoc legacy
+ordering. In such cases, you may find that you get an unexpected value
+returned when adapting one or more objects to an interface. To debug
+this, *also* enable ``ZOPE_INTERFACE_LOG_CHANGED_IRO`` and examine the
+output. The main thing to look for is changes in the relative
+positions of interfaces for which there are registered adapters.
 """
 from __future__ import print_function
 __docformat__ = 'restructuredtext'
diff --git a/src/zope/interface/tests/test_declarations.py b/src/zope/interface/tests/test_declarations.py
index 29b75e9..f4354fe 100644
--- a/src/zope/interface/tests/test_declarations.py
+++ b/src/zope/interface/tests/test_declarations.py
@@ -1305,10 +1305,16 @@ class ProvidesClassTests(unittest.TestCase):
         self.assertRaises(AttributeError, _test)
 
     def test__repr__(self):
-        inst = self._makeOne(type(self))
+        from zope.interface.interface import InterfaceClass
+        IFoo = InterfaceClass("IFoo")
+
+        inst = self._makeOne(type(self), IFoo)
         self.assertEqual(
             repr(inst),
-            "<zope.interface.Provides for %r>"  % type(self)
+            "<zope.interface.Provides for instances of %r providing %s>"  % (
+                type(self),
+                (IFoo,)
+            )
         )