Reorganize the 'declarations' document by functional group.

Add cross references and some formatting fixes.

2 files changed, 42 insertions, 42 deletions

diff --git a/src/zope/interface/declarations.py b/src/zope/interface/declarations.py
index acea120..b80245f 100644
--- a/src/zope/interface/declarations.py
+++ b/src/zope/interface/declarations.py
@@ -214,7 +214,7 @@ def _implements_name(ob):
 def implementedByFallback(cls):
     """Return the interfaces implemented for a class' instances
 
-      The value returned is an IDeclaration.
+      The value returned is an `~zope.interface.interfaces.IDeclaration`.
     """
     try:
         spec = cls.__dict__.get('__implemented__')
@@ -302,7 +302,7 @@ def classImplementsOnly(cls, *interfaces):
     """Declare the only interfaces implemented by instances of a class
 
       The arguments after the class are one or more interfaces or interface
-      specifications (``IDeclaration`` objects).
+      specifications (`~zope.interface.interfaces.IDeclaration` objects).
 
       The interfaces given (including the interfaces in the specifications)
       replace any previous declarations.
@@ -316,7 +316,7 @@ def classImplements(cls, *interfaces):
     """Declare additional interfaces implemented for instances of a class
 
       The arguments after the class are one or more interfaces or
-      interface specifications (``IDeclaration`` objects).
+      interface specifications (`~zope.interface.interfaces.IDeclaration` objects).
 
       The interfaces given (including the interfaces in the specifications)
       are added to any interfaces previously declared.
@@ -349,13 +349,13 @@ def _implements_advice(cls):
     return cls
 
 
-class implementer:
+class implementer(object):
     """Declare the interfaces implemented by instances of a class.
 
       This function is called as a class decorator.
 
       The arguments are one or more interfaces or interface
-      specifications (IDeclaration objects).
+      specifications (`~zope.interface.interfaces.IDeclaration` objects).
 
       The interfaces given (including the interfaces in the
       specifications) are added to any interfaces previously
@@ -365,7 +365,7 @@ class implementer:
       unless implementsOnly was used.
 
       This function is provided for convenience. It provides a more
-      convenient way to call classImplements. For example::
+      convenient way to call `classImplements`. For example::
 
         @implementer(I1)
         class C(object):
@@ -394,19 +394,19 @@ class implementer:
             raise TypeError("Can't declare implements", ob)
         return ob
 
-class implementer_only:
+class implementer_only(object):
     """Declare the only interfaces implemented by instances of a class
 
       This function is called as a class decorator.
 
       The arguments are one or more interfaces or interface
-      specifications (IDeclaration objects).
+      specifications (`~zope.interface.interfaces.IDeclaration` objects).
 
       Previous declarations including declarations for base classes
       are overridden.
 
       This function is provided for convenience. It provides a more
-      convenient way to call classImplementsOnly. For example::
+      convenient way to call `classImplementsOnly`. For example::
 
         @implementer_only(I1)
         class C(object): pass
@@ -457,17 +457,17 @@ def implements(*interfaces):
       This function is called in a class definition.
 
       The arguments are one or more interfaces or interface
-      specifications (IDeclaration objects).
+      specifications (`~zope.interface.interfaces.IDeclaration` objects).
 
       The interfaces given (including the interfaces in the
       specifications) are added to any interfaces previously
       declared.
 
       Previous declarations include declarations for base classes
-      unless implementsOnly was used.
+      unless `implementsOnly` was used.
 
       This function is provided for convenience. It provides a more
-      convenient way to call classImplements. For example::
+      convenient way to call `classImplements`. For example::
 
         implements(I1)
 
@@ -489,13 +489,13 @@ def implementsOnly(*interfaces):
       This function is called in a class definition.
 
       The arguments are one or more interfaces or interface
-      specifications (IDeclaration objects).
+      specifications (`~zope.interface.interfaces.IDeclaration` objects).
 
       Previous declarations including declarations for base classes
       are overridden.
 
       This function is provided for convenience. It provides a more
-      convenient way to call classImplementsOnly. For example::
+      convenient way to call `classImplementsOnly`. For example::
 
         implementsOnly(I1)
 
@@ -516,7 +516,7 @@ def implementsOnly(*interfaces):
 # Instance declarations
 
 class Provides(Declaration):  # Really named ProvidesClass
-    """Implement __provides__, the instance-specific specification
+    """Implement ``__provides__``, the instance-specific specification
 
     When an object is pickled, we pickle the interfaces that it implements.
     """
@@ -568,7 +568,7 @@ def directlyProvides(object, *interfaces):
     """Declare interfaces declared directly for an object
 
       The arguments after the object are one or more interfaces or interface
-      specifications (``IDeclaration`` objects).
+      specifications (`~zope.interface.interfaces.IDeclaration` objects).
 
       The interfaces given (including the interfaces in the specifications)
       replace interfaces previously declared for the object.
@@ -604,7 +604,7 @@ def alsoProvides(object, *interfaces):
     """Declare interfaces declared directly for an object
 
     The arguments after the object are one or more interfaces or interface
-    specifications (``IDeclaration`` objects).
+    specifications (`~zope.interface.interfaces.IDeclaration` objects).
 
     The interfaces given (including the interfaces in the specifications) are
     added to the interfaces previously declared for the object.
@@ -646,7 +646,7 @@ else:
 
 
 class ClassProvides(Declaration, ClassProvidesBase):
-    """Special descriptor for class __provides__
+    """Special descriptor for class ``__provides__``
 
     The descriptor caches the implementedBy info, so that
     we can get declarations for objects without instance-specific
@@ -667,7 +667,7 @@ class ClassProvides(Declaration, ClassProvidesBase):
 def directlyProvidedBy(object):
     """Return the interfaces directly provided by the given object
 
-    The value returned is an ``IDeclaration``.
+    The value returned is an `~zope.interface.interfaces.IDeclaration`.
     """
     provides = getattr(object, "__provides__", None)
     if (provides is None # no spec
@@ -688,7 +688,7 @@ def classProvides(*interfaces):
       This function is called in a class definition.
 
       The arguments are one or more interfaces or interface specifications
-      (``IDeclaration`` objects).
+      (`~zope.interface.interfaces.IDeclaration` objects).
 
       The given interfaces (including the interfaces in the specifications)
       are used to create the class's direct-object interface specification.
@@ -700,7 +700,7 @@ def classProvides(*interfaces):
       implemented by instances of the class.
 
       This function is provided for convenience. It provides a more convenient
-      way to call directlyProvides for a class. For example::
+      way to call `directlyProvides` for a class. For example::
 
         classProvides(I1)
 
@@ -740,7 +740,7 @@ def _classProvides_advice(cls):
     directlyProvides(cls, *interfaces)
     return cls
 
-class provider:
+class provider(object):
     """Class decorator version of classProvides"""
 
     def __init__(self, *interfaces):
@@ -756,7 +756,7 @@ def moduleProvides(*interfaces):
     This function is used in a module definition.
 
     The arguments are one or more interfaces or interface specifications
-    (``IDeclaration`` objects).
+    (`~zope.interface.interfaces.IDeclaration` objects).
 
     The given interfaces (including the interfaces in the specifications) are
     used to create the module's direct-object interface specification.  An
diff --git a/src/zope/interface/interfaces.py b/src/zope/interface/interfaces.py
index 69194ce..27e64e9 100644
--- a/src/zope/interface/interfaces.py
+++ b/src/zope/interface/interfaces.py
@@ -421,7 +421,7 @@ class IInterfaceDeclaration(Interface):
         """
 
     def implementer(*interfaces):
-        """Create a decorator for declaring interfaces implemented by a facory
+        """Create a decorator for declaring interfaces implemented by a factory.
 
         A callable is returned that makes an implements declaration on
         objects passed to it.
@@ -431,7 +431,7 @@ class IInterfaceDeclaration(Interface):
         """Declare the only interfaces implemented by instances of a class
 
         The arguments after the class are one or more interfaces or
-        interface specifications (IDeclaration objects).
+        interface specifications (`IDeclaration` objects).
 
         The interfaces given (including the interfaces in the
         specifications) replace any previous declarations.
@@ -458,14 +458,14 @@ class IInterfaceDeclaration(Interface):
     def directlyProvidedBy(object):
         """Return the interfaces directly provided by the given object
 
-        The value returned is an IDeclaration.
+        The value returned is an `IDeclaration`.
         """
 
     def directlyProvides(object, *interfaces):
         """Declare interfaces declared directly for an object
 
         The arguments after the object are one or more interfaces or
-        interface specifications (IDeclaration objects).
+        interface specifications (`IDeclaration` objects).
 
         The interfaces given (including the interfaces in the
         specifications) replace interfaces previously
@@ -482,7 +482,7 @@ class IInterfaceDeclaration(Interface):
         The object, ``ob`` provides ``I1``, ``I2``, and whatever interfaces
         instances have been declared for instances of ``C``.
 
-        To remove directly provided interfaces, use ``directlyProvidedBy`` and
+        To remove directly provided interfaces, use `directlyProvidedBy` and
         subtract the unwanted interfaces. For example::
 
           directlyProvides(ob, directlyProvidedBy(ob)-I2)
@@ -492,7 +492,7 @@ class IInterfaceDeclaration(Interface):
         although it might still provide ``I2`` if it's class
         implements ``I2``.
 
-        To add directly provided interfaces, use ``directlyProvidedBy`` and
+        To add directly provided interfaces, use `directlyProvidedBy` and
         include additional interfaces.  For example::
 
           directlyProvides(ob, directlyProvidedBy(ob), I2)
@@ -518,11 +518,11 @@ class IInterfaceDeclaration(Interface):
 
         is equivalent to::
 
-          directlyProvides(ob, directlyProvidedBy(ob)-I1)
+          directlyProvides(ob, directlyProvidedBy(ob) - I1)
 
         with the exception that if ``I1`` is an interface that is
         provided by ``ob`` through the class's implementation,
-        ValueError is raised.
+        `ValueError` is raised.
         """
 
     def implements(*interfaces):
@@ -531,7 +531,7 @@ class IInterfaceDeclaration(Interface):
         This function is called in a class definition (Python 2.x only).
 
         The arguments are one or more interfaces or interface
-        specifications (IDeclaration objects).
+        specifications (`IDeclaration` objects).
 
         The interfaces given (including the interfaces in the
         specifications) are added to any interfaces previously
@@ -541,7 +541,7 @@ class IInterfaceDeclaration(Interface):
         unless implementsOnly was used.
 
         This function is provided for convenience. It provides a more
-        convenient way to call classImplements. For example::
+        convenient way to call `classImplements`. For example::
 
           implements(I1)
 
@@ -567,13 +567,13 @@ class IInterfaceDeclaration(Interface):
         This function is called in a class definition (Python 2.x only).
 
         The arguments are one or more interfaces or interface
-        specifications (IDeclaration objects).
+        specifications (`IDeclaration` objects).
 
         Previous declarations including declarations for base classes
         are overridden.
 
         This function is provided for convenience. It provides a more
-        convenient way to call classImplementsOnly. For example::
+        convenient way to call `classImplementsOnly`. For example::
 
           implementsOnly(I1)
 
@@ -599,7 +599,7 @@ class IInterfaceDeclaration(Interface):
         This function is called in a class definition.
 
         The arguments are one or more interfaces or interface
-        specifications (IDeclaration objects).
+        specifications (`IDeclaration` objects).
 
         The given interfaces (including the interfaces in the
         specifications) are used to create the class's direct-object
@@ -612,7 +612,7 @@ class IInterfaceDeclaration(Interface):
         interfaces implemented by instances of the class.
 
         This function is provided for convenience. It provides a more
-        convenient way to call directlyProvides for a class. For example::
+        convenient way to call `directlyProvides` for a class. For example::
 
           classProvides(I1)
 
@@ -623,7 +623,7 @@ class IInterfaceDeclaration(Interface):
         after the class has been created.
         """
     def provider(*interfaces):
-        """A class decorator version of classProvides"""
+        """A class decorator version of `classProvides`"""
 
     def moduleProvides(*interfaces):
         """Declare interfaces provided by a module
@@ -631,7 +631,7 @@ class IInterfaceDeclaration(Interface):
         This function is used in a module definition.
 
         The arguments are one or more interfaces or interface
-        specifications (IDeclaration objects).
+        specifications (`IDeclaration` objects).
 
         The given interfaces (including the interfaces in the
         specifications) are used to create the module's direct-object
@@ -641,7 +641,7 @@ class IInterfaceDeclaration(Interface):
         definition.
 
         This function is provided for convenience. It provides a more
-        convenient way to call directlyProvides for a module. For example::
+        convenient way to call `directlyProvides` for a module. For example::
 
           moduleImplements(I1)
 
@@ -654,9 +654,9 @@ class IInterfaceDeclaration(Interface):
         """Create an interface specification
 
         The arguments are one or more interfaces or interface
-        specifications (IDeclaration objects).
+        specifications (`IDeclaration` objects).
 
-        A new interface specification (IDeclaration) with
+        A new interface specification (`IDeclaration`) with
         the given interfaces is returned.
         """