From 5f6d95af055ffc90ff60bde2d028919bc1c891f7 Mon Sep 17 00:00:00 2001
From: dieter <dieter@handshake.de>
Date: Thu, 24 Aug 2023 07:36:14 +0200
Subject: [PATCH] improve `declarations.Provides` documentation; especially
 document the correct signature

---
 src/zope/interface/declarations.py | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/src/zope/interface/declarations.py b/src/zope/interface/declarations.py
index b3e3f21b..61e25439 100644
--- a/src/zope/interface/declarations.py
+++ b/src/zope/interface/declarations.py
@@ -789,7 +789,11 @@ def __get__(self, inst, cls):
 InstanceDeclarations = weakref.WeakValueDictionary()
 
 def Provides(*interfaces): # pylint:disable=function-redefined
-    """Cache instance declarations
+    """Declaration for an instance of *cls*.
+
+       The correct signature is ``cls, *interfaces``.
+       The *cls* is necessary to avoid the
+       construction of inconsistent resolution orders.
 
       Instance declarations are shared among instances that have the same
       declaration. The declarations are cached in a weak value dictionary.