Add documentation for taggedValue and invariant.

docs/README.rst

@@ -718,6 +718,8 @@ that lists the specification and all of it's ancestors:
 Tagged Values
 =============
 
+.. autofunction:: taggedValue
+
 Interfaces and attribute descriptions support an extension mechanism,
 borrowed from UML, called "tagged values" that lets us store extra
 data:
@@ -780,9 +782,12 @@ versions of functions.
    >>> IExtendsIWithTaggedValues.getDirectTaggedValue('squish')
    'SQUASH'
 
+
 Invariants
 ==========
 
+.. autofunction:: invariant
+
 Interfaces can express conditions that must hold for objects that
 provide them. These conditions are expressed using one or more
 invariants.  Invariants are callable objects that will be called with

docs/api/declarations.rst

@@ -18,6 +18,24 @@ carefully at each object it documents, including providing examples.
 
 .. currentmodule:: zope.interface
 
+Declaring Interfaces
+====================
+
+To declare an interface itself, extend the ``Interface`` base class.
+
+.. autointerface:: Interface
+   :noindex:
+
+.. autofunction:: taggedValue
+   :noindex:
+
+   .. documented more thoroughly in README.rst
+
+.. autofunction:: invariant
+   :noindex:
+
+   .. documented in README.rst
+
 Declaring The Interfaces of Objects
 ===================================
 

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.