Formatting and cross refs for the 'Interface Specification' doc

docs/api/specifications.rst

@@ -2,17 +2,19 @@
  Interface Specifications
 ==========================
 
+.. currentmodule:: zope.interface.interfaces
+
+
+This document discusses the actual interface objects themselves. The
+broader concept is of "specifications."
 
 ``zope.interface.interface.Specification``
 ==========================================
 
-API
----
-
 Specification objects implement the API defined by
-:class:`zope.interface.interfaces.ISpecification`:
+:class:`ISpecification`:
 
-.. autointerface:: zope.interface.interfaces.ISpecification
+.. autointerface:: ISpecification
    :members:
    :member-order: bysource
 
@@ -160,15 +162,29 @@ Exmples for :meth:`Specification.extends`:
 ``zope.interface.Interface``
 ============================
 
-API
----
+Interfaces are a particular type of `ISpecification` and implement the
+API defined by :class:`IInterface`.
 
-Interfaces are a specilization of `ISpecification` and implement the
-API defined by :class:`zope.interface.interfaces.IInterface`:
+Before we get there, we need to discuss two related concepts. The
+first is that of an "element", which provides us a simple way to query
+for information generically (this is important because we'll see that
+``IInterface`` implements this interface):
 
-.. autointerface:: zope.interface.interfaces.IInterface
-   :members:
-   :member-order: bysource
+.. autointerface:: IElement
+.. autoclass:: zope.interface.interface.Element
+   :no-members:
+
+Next, we look at ``IAttribute`` and ``IMethod``. These make up the
+content, or body, of an ``Interface``.
+
+.. autointerface:: zope.interface.interfaces.IAttribute
+.. autoclass:: zope.interface.interface.Attribute
+
+.. autoclass:: IMethod
+
+Finally we can look at the definition of ``IInterface``.
+
+.. autointerface:: IInterface
 
 .. autoclass:: zope.interface.Interface
 

src/zope/interface/interface.py

@@ -48,15 +48,16 @@ def taggedValue(key, value):
 
 
 class Element(object):
+    """
+    Default implementation of `zope.interface.interfaces.IElement`.
+    """
 
     # We can't say this yet because we don't have enough
     # infrastructure in place.
     #
     #implements(IElement)
 
     def __init__(self, __name__, __doc__=''):
-        """Create an 'attribute' description
-        """
         if not __doc__ and __name__.find(' ') >= 0:
             __doc__ = __name__
             __name__ = None

src/zope/interface/interfaces.py

@@ -163,16 +163,16 @@ class IInterface(ISpecification, IElement):
     Interface objects describe the behavior of an object by containing
     useful information about the object.  This information includes:
 
-      o Prose documentation about the object.  In Python terms, this
-        is called the "doc string" of the interface.  In this element,
-        you describe how the object works in prose language and any
-        other useful information about the object.
+    - Prose documentation about the object.  In Python terms, this
+      is called the "doc string" of the interface.  In this element,
+      you describe how the object works in prose language and any
+      other useful information about the object.
 
-      o Descriptions of attributes.  Attribute descriptions include
-        the name of the attribute and prose documentation describing
-        the attributes usage.
+    - Descriptions of attributes.  Attribute descriptions include
+      the name of the attribute and prose documentation describing
+      the attributes usage.
 
-      o Descriptions of methods.  Method descriptions can include:
+    - Descriptions of methods.  Method descriptions can include:
 
         - Prose "doc string" documentation about the method and its
           usage.
@@ -183,12 +183,12 @@ class IInterface(ISpecification, IElement):
           method accepts arbitrary arguments and whether the method
           accepts arbitrary keyword arguments.
 
-      o Optional tagged data.  Interface objects (and their attributes and
-        methods) can have optional, application specific tagged data
-        associated with them.  Examples uses for this are examples,
-        security assertions, pre/post conditions, and other possible
-        information you may want to associate with an Interface or its
-        attributes.
+    - Optional tagged data.  Interface objects (and their attributes and
+      methods) can have optional, application specific tagged data
+      associated with them.  Examples uses for this are examples,
+      security assertions, pre/post conditions, and other possible
+      information you may want to associate with an Interface or its
+      attributes.
 
     Not all of this information is mandatory.  For example, you may
     only want the methods of your interface to have prose
@@ -197,7 +197,7 @@ class IInterface(ISpecification, IElement):
     take any of these components.
 
     Interfaces are created with the Python class statement using
-    either Interface.Interface or another interface, as in::
+    either `zope.interface.Interface` or another interface, as in::
 
       from zope.interface import Interface
 
@@ -217,16 +217,16 @@ def meth2():
 
     You use interfaces in two ways:
 
-    o You assert that your object implement the interfaces.
+    - You assert that your object implement the interfaces.
 
       There are several ways that you can assert that an object
       implements an interface:
 
-      1. Call zope.interface.implements in your class definition.
+      1. Call `zope.interface.implements` in your class definition.
 
-      2. Call zope.interfaces.directlyProvides on your object.
+      2. Call `zope.interfaces.directlyProvides` on your object.
 
-      3. Call 'zope.interface.classImplements' to assert that instances
+      3. Call `zope.interface.classImplements` to assert that instances
          of a class implement an interface.
 
          For example::
@@ -240,7 +240,7 @@ def meth2():
          class itself implements, but only what its instances
          implement.
 
-    o You query interface meta-data. See the IInterface methods and
+    - You query interface meta-data. See the IInterface methods and
       attributes for details.
 
     """
@@ -271,7 +271,7 @@ def namesAndDescriptions(all=False):
     def __getitem__(name):
         """Get the description for a name
 
-        If the named attribute is not defined, a KeyError is raised.
+        If the named attribute is not defined, a `KeyError` is raised.
         """
 
     def direct(name):
@@ -389,20 +389,20 @@ def providedBy(ob):
         This is the union of the interfaces directly provided by an
         object and interfaces implemented by it's class.
 
-        The value returned is an IDeclaration.
+        The value returned is an `IDeclaration`.
         """
 
     def implementedBy(class_):
         """Return the interfaces implemented for a class' instances
 
-        The value returned is an IDeclaration.
+        The value returned is an `IDeclaration`.
         """
 
     def classImplements(class_, *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 (`IDeclaration` objects).
 
         The interfaces given (including the interfaces in the
         specifications) are added to any interfaces previously