Reference documentation improvementsdoc-module

- Make it possible to use :mod:`zope.component`
- Provide a concise list of all the available APIs in that module and
  link them to their in-depth descriptions.
- Fix several xref errors
- Add documentation for setHooks/resetHooks.

This also makes it possible to get useful help at the REPL or command
line:

$ python -c 'import zope.component; help(zope.component.getAdapters)'
Help on function getAdapters in module zope.component._api:

getAdapters(objects, provided, context=None)
    Look for all matching adapters to a provided interface for
    objects

    Return a list of adapters that match. If an adapter is named,
    only the most specific adapter of a given name is returned.

    .. seealso::
       Function `~zope.component.getAdapters` for notes, and
       `~zope.component.interfaces.IComponentArchitecture` for the defining interface.

1 files changed, 9 insertions, 0 deletions

diff --git a/src/zope/component/_declaration.py b/src/zope/component/_declaration.py
index db3d1c3..5e75d85 100644
--- a/src/zope/component/_declaration.py
+++ b/src/zope/component/_declaration.py
@@ -18,7 +18,13 @@ import sys
 from zope.component._compat import CLASS_TYPES
 
 class adapter(object):
+    """
+    Decorator that declares that the decorated object adapts the given
+    *interfaces*.
 
+    This is commonly used in conjunction with :obj:`zope.interface.implementer`
+    to declare what adapting the *interfaces* will provide.
+    """
     def __init__(self, *interfaces):
         self.interfaces = interfaces
 
@@ -44,6 +50,9 @@ def adapts(*interfaces):
     locals['__component_adapts__'] = _adapts_descr(interfaces)
 
 def adaptedBy(ob):
+    """
+    Return the *interfaces* that *ob* will adapt, as declared by :obj:`adapter`.
+    """
     return getattr(ob, '__component_adapts__', None)
 
 def getName(ob):