[Checkins] SVN: grokcore.component/trunk/src/grokcore/component/ add a bit of documentation for the subscription components

[Jan-Wijbrand Kolman]

Log message for revision 120313:
  add a bit of documentation for the subscription components

Changed:
  U   grokcore.component/trunk/src/grokcore/component/components.py
  U   grokcore.component/trunk/src/grokcore/component/directive.py

-=-
Modified: grokcore.component/trunk/src/grokcore/component/components.py
===================================================================
--- grokcore.component/trunk/src/grokcore/component/components.py	2011-02-14 09:43:15 UTC (rev 120312)
+++ grokcore.component/trunk/src/grokcore/component/components.py	2011-02-14 09:52:49 UTC (rev 120313)
@@ -27,8 +27,6 @@
     provide. If it's a named adapter, you may use the ``name`` directive to
     specify the name.
 
-    Adapters are automatically registered when a module is "grokked".
-
     .. attribute:: context
 
        The adapted object.
@@ -51,8 +49,6 @@
     provide an `__init__` method. An `__init__` needs to accept the same number
     of arguments as are used in the `adapts` directive.
 
-    MultiAdapters are automatically registered when a module is "grokked".
-
     """
     pass
 
@@ -69,9 +65,6 @@
     implemented interfaces should be used when registering the utility. If it's
     a named utility, you may use the ``name`` directive to specify the name.
 
-
-    Global utilities are automatically registered when a module is "grokked".
-
     """
     pass
 
@@ -83,7 +76,11 @@
     register multiple unnamed subscriptions for identical ``context`` and
     ``provides``.
 
-    Use the ``adapts`` directive
+    Use the ``context`` directive to explicitly set the interface to adapt
+    from. When omitted the current context is assumed. Use the ``implements``
+    directive to specify which interface the subscription provides, or if that
+    is not unambiguous, also use the ``provides`` directive to specify which of
+    the implemented interfaces should be used when registering the subscription.
 
     """
 
@@ -93,6 +90,17 @@
 
 class MultiSubscription(object):
     """Base class for a subscription multi-adapter.
+
+    MultiSubscriptions are similar to multi adapters, except that it is
+    possible to register multiple unnamed subscriptions for identical
+    ``adapts`` and ``provides``.
+
+    Use the ``adapts`` directive to explicitly set the multiple interfaces to
+    adapt from. Use the ``implements`` directive to specify which interface the
+    subscription provides, or if that is not unambiguous, also use the
+    ``provides`` directive to specify which of the implemented interfaces
+    should be used when registering the multi subscription.
+
     """
 
 

Modified: grokcore.component/trunk/src/grokcore/component/directive.py
===================================================================
--- grokcore.component/trunk/src/grokcore/component/directive.py	2011-02-14 09:43:15 UTC (rev 120312)
+++ grokcore.component/trunk/src/grokcore/component/directive.py	2011-02-14 09:52:49 UTC (rev 120313)
@@ -55,7 +55,7 @@
     :param adapts: Optionally, a single interface or a tuple of multiple
                    interfaces to adapts from. If omitted, this information is
                    deduced from the annotation on the factory. If no adapted
-                   interface can be determinedm the current context will be
+                   interface can be determined the current context will be
                    assumed.
     :param provides: Optionally, the interface the adapter will provide. If
                      omitted, this information is deduced from the annotations