Add documentation for taggedValue and invariant.

1 files changed, 51 insertions, 0 deletions

diff --git a/src/zope/interface/interfaces.py b/src/zope/interface/interfaces.py
index 3f1bf9f..c0ece6a 100644
--- a/src/zope/interface/interfaces.py
+++ b/src/zope/interface/interfaces.py
@@ -473,8 +473,55 @@ class IInterfaceDeclaration(Interface):
     directly. The interfaces provided by an object are the union of
     the interfaces provided directly and the interfaces implemented by
     the class.
+
+    This interface is implemented by :mod:`zope.interface`.
     """
 
+    ###
+    # Defining interfaces
+    ###
+
+    Interface = Attribute("The base class used to create new interfaces")
+
+    def taggedValue(key, value):
+        """
+        Attach a tagged value to an interface while defining the interface.
+
+        This is a way of executing :meth:`IElement.setTaggedValue` from
+        the definition of the interface. For example::
+
+            class IFoo(Interface):
+                 taggedValue('key', 'value')
+
+        .. seealso:: `zope.interface.taggedValue`
+        """
+
+    def invariant(checker_function):
+        """
+        Attach an invariant checker function to an interface while defining it.
+
+        Invariants can later be validated against particular implementations by
+        calling :meth:`IInterface.validateInvariants`.
+
+        For example::
+
+            def check_range(ob):
+                if ob.max < ob.min:
+                    range ValueError
+
+            class IRange(Interface):
+                min = Attribute("The min value")
+                max = Attribute("The max value")
+
+                invariant(check_range)
+
+        .. seealso:: `zope.interface.invariant`
+        """
+
+    ###
+    # Querying interfaces
+    ###
+
     def providedBy(ob):
         """
         Return the interfaces provided by an object.
@@ -496,6 +543,10 @@ class IInterfaceDeclaration(Interface):
         .. seealso:: `zope.interface.implementedBy`
         """
 
+    ###
+    # Declaring interfaces
+    ###
+
     def classImplements(class_, *interfaces):
         """
         Declare additional interfaces implemented for instances of a class.