[Zope-Checkins] CVS: Zope3/lib/python/Zope/Configuration - meta.py:1.1.2.9.14.2

[Jim Fulton]

Update of /cvs-repository/Zope3/lib/python/Zope/Configuration
In directory cvs.zope.org:/tmp/cvs-serv13967

Modified Files:
      Tag: Zope3InWonderland-branch
	meta.py 
Log Message:
Added some doc strings and comments to, hopefully, make what's going
on a bit clearer.


=== Zope3/lib/python/Zope/Configuration/meta.py 1.1.2.9.14.1 => 1.1.2.9.14.2 ===
 """
 
+# 
+
 from ConfigurationDirectiveInterfaces import INonEmptyDirective
 from ConfigurationDirectiveInterfaces import ISubdirectiveHandler
 
@@ -30,11 +32,47 @@
     "A directive is implemented incorrectly"
 
 def register(name, callable):
+    """Register a top-level directive
+
+    The name argument is a tuple with a namespace URI and an
+    name string.
+
+    The callable must be am IEmptyDirective or an INonEmptyDirective.
+
+    INonEmptyDirective directives may have subdirectives. The
+    subdirectives will be registered in a registry that is stored with
+    the directive. The sub-directive registry is returned so that
+    it can be used for subsequent sub-directive registration.
+
+    """
+    
     subdirs = {}
     _directives[name] = callable, subdirs
     return subdirs
 
 def registersub(directives, name, handler_method=None):
+    """Register a subdirective
+
+    directives is the subdirective registry for the containing
+    directive, which may be either a top-level directive or an
+    intermediate sub-directive (if subdirectives are nested more than
+    two deep.
+
+    The name argument is a tuple with a namespace URI and an
+    name string.
+
+    The handler is not passed as it normally is for top-level
+    directives. Rather, the handler is looked up as an attribute of
+    the top-level directive object using the name string that is the
+    second element in the name tuple.  An optional handler attribute
+    can be used to specify the method to be used.
+
+    Subdirectives may have subdirectives. The subdirectives will be
+    registered in a registry that is stored with the containing
+    subdirective. The sub-directive registry is returned so that it
+    can be used for subsequent sub-directive registration.
+
+    """
     if not handler_method:
         handler_method = name[1]
     subdirs = {}
@@ -47,9 +85,41 @@
     if subs or INonEmptyDirective.isImplementedBy(callable):
         return r, subs
     else:
-        return lambda: r, subs
+        return (
+            # We already have our list of actions, but we're expected to
+            # provide a callable that returns one. 
+            (lambda: r),
+
+            subs,
+            )
 
 def begin(_custom_directives, _name, _context, **kw):
+    """Begin executing a top-level directive
+
+    A custom registry is provided to provides specialized directive
+    handlers in addition to the globally registered directives. For
+    example, the XML configuration mechanism uses these to provide XML
+    configuration file directives.
+
+    The _name argument is a tuple with a namespace URI and an
+    name string.
+
+    Thje _context argument is an execution context objects that
+    directives use for functions like resolving names. It will be
+    passed as the first argument to the directive handler.
+
+    kw are the directive arguments.
+
+    The return value is a tuple that contains:
+
+    - An object to be called to finish directive processing. This
+      object will return a sequence of actions. The object must be
+      called after sub-directives are processes.
+
+    - A registry for looking up subdirectives.
+
+    """
+    
     if _custom_directives and (_name in _custom_directives):
         callable, subs = _custom_directives[_name]
     else:
@@ -61,6 +131,30 @@
     return _exe(callable, subs, _context, kw)
 
 def sub(subs, _name, _context, **kw):
+    """Begin executing a subdirective
+
+    The first argument, subs, is a registry of allowable subdirectives
+    for the containing directive or subdirective.
+
+    The _name argument is a tuple with a namespace URI and an
+    name string.
+
+    Thje _context argument is an execution context objects that
+    directives use for functions like resolving names. It will be
+    passed as the first argument to the directive handler.
+
+    kw are the directive arguments.
+
+    The return value is a tuple that contains:
+
+    - An object to be called to finish directive processing. This
+      object will return a sequence of actions. The object must be
+      called after sub-directives are processes.
+
+    - A registry for looking up subdirectives.
+
+    """
+
     base, subdirs = subs
     try:
         subs = subdirs[_name]
@@ -83,6 +177,16 @@
 
 defaultkw = ({},)
 def end(base):
+    """Finish processing a directive or subdirective
+
+    The argument is a return value from begin or sub. It's first
+    element is called to get a sequence of actions.
+
+    The actions are normalized to a 4-element tuple with a
+    descriminator, a callable, positional arguments, and keyword
+    arguments. 
+    """
+
     actions = base[0]()
     ractions = []
     for action in actions: