[Checkins] SVN: grok/trunk/src/grok/directive.py Created docstrings for all the Grok-specific directives. These strings

[Brandon Rhodes]

Log message for revision 94456:
  Created docstrings for all the Grok-specific directives.  These strings
  might be far too verbose, depending on what we actually need to know
  about a directive when reading its definition; some of them certainly
  describe things that take place elsewhere within the Grok code base,
  rather than in the code directly below the docstring.  The comments
  supply the minimal context that I, at least, would need in order to
  understand what is going on; but an argument could be made that some of
  this material should be moved to the Grok reference instead, where, last
  I checked, several of these directives do not yet have documentation.
  
  The docstrings might also be wrong, of course, since they sometimes
  include specific information of which I was not entirely sure; but I
  would prefer them to be wrong-and-specific and get fixed, rather than
  so vague that they do not invite improvement.
  

Changed:
  U   grok/trunk/src/grok/directive.py

-=-
Modified: grok/trunk/src/grok/directive.py
===================================================================
--- grok/trunk/src/grok/directive.py	2009-01-02 18:20:03 UTC (rev 94455)
+++ grok/trunk/src/grok/directive.py	2009-01-02 19:05:24 UTC (rev 94456)
@@ -12,21 +12,64 @@
 #
 ##############################################################################
 """Grok directives.
+
+This module defines Grok directives: the markers that users place inside
+of their classes (and sometimes in their modules, too) to direct how
+Grok registers their components.  For example, the first directive
+defined below is `local_utility`, which people programming Grok
+applications normally use like this::
+
+    class MyUtility(grok.Utility):
+        grok.local_utility()
+        ...
+
+If the set of directives in this module looks rather small, remember
+that most of the directives available in Grok actually come from the
+`grokcore` modules on which Grok depends, where they have been placed so
+that other projects can use them without having to pull in all of Grok.
+
 """
-
 import grok
 from zope import interface
 from zope.interface.interfaces import IInterface
 
 import martian
 from martian import util
-from martian.error import GrokImportError, GrokError
-from martian.directive import StoreOnce, StoreMultipleTimes
-from grokcore.component.scan import UnambiguousComponentScope
+from martian.error import GrokImportError
 from grokcore.view.directive import TaggedValueStoreOnce
-from grok import components
 
 class local_utility(martian.Directive):
+    """The `grok.local_utility()` directive.
+
+    Place this directive inside of a `grok.Application` or `grok.Site`
+    subclass, and provide the name of a utility you want activated
+    inside of that site::
+
+        class MySite(grok.Site):
+            grok.local_utility(MyMammothUtility)
+            ...
+
+    This directive can be supplied several times within the same site.
+    Thanks to the presence of this directive, any time an instance of
+    your class is created in the Zope database it will have a copy of
+    the given local utility installed along with it.
+
+    This directive accepts several normal Component-registration keyword
+    arguments, like `provides` and `name`, and uses them each time it
+    registers your local utility.
+
+    If you do not supply a `provides` keyword, then Grok attempts to
+    guess a sensible default.  Its first choice is to use any
+    interface(s) that you listed with the grok.provides() directive when
+    defining your utility.  Otherwise, if your utility is a subclass of
+    `grok.localUtility`, then Grok will use any interfaces that your
+    utility supplies beyond those are supplied because of its
+    inheritance from `grok.localUtility`.  Else, as a final fallback, it
+    checks to see whether the class you are registering supplies one,
+    and only one, interface; if so, then it can register the utility
+    unambiguously as providing that one interface.
+
+    """
     scope = martian.CLASS
     store = martian.DICT
 
@@ -73,7 +116,17 @@
 
 
 class LocalUtilityInfo(object):
+    """The information about how to register a local utility.
 
+    An instance of this class is created for each `grok.local_utility()`
+    in a Grok application's code, to remember how the user wants their
+    local utility registered.  Later, whenever the application creates
+    new instances of the site or application for which the local utility
+    directive was supplied, this block of information is used as the
+    parameters to the creation of the local utility which is created
+    along with the new site in the Zope database.
+
+    """
     _order = 0
 
     def __init__(self, factory, provides, name=u'',
@@ -95,11 +148,30 @@
 
 
 class site(martian.Directive):
+    """The `grok.site()` directive.
+
+    This directive is used when creating a `grok.Indexes` subclass, to
+    indicate the Grok site object for which the indexes should be built.
+
+    """
     scope = martian.CLASS
     store = martian.ONCE
     validate = martian.validateInterfaceOrClass
 
 class permissions(martian.Directive):
+    """The `grok.permissions()` directive.
+
+    This directive is used inside of a `grok.Role` subclass to list the
+    permissions which each member of the role should always possess.
+    Note that permissions should be passed as strings, and that several
+    permissions they can simply be supplied as multiple arguments; there
+    is no need to place them inside of a tuple or list::
+
+        class MyRole(grok.Role):
+            grok.permissions('page.CreatePage', 'page.EditPage')
+            ...
+
+    """
     scope = martian.CLASS
     store = martian.ONCE
     default = []
@@ -108,6 +180,24 @@
         return args
 
 class traversable(martian.Directive):
+    """The `grok.traversable()` directive.
+
+    Each time this directive is used inside of a class, it designates an
+    attribute of that class which URLs should be able to traverse.  For
+    example, the declaration:
+
+        class Mammoth(grok.Model):
+            grok.traversable('thighbone')
+
+    means that if the URL `/app/mymammoth` designates a Mammoth, then
+    `/app/mymammoth/thighbone` will also be a valid URL (assuming that
+    the Mammoth instance, at runtime, indeed has an attribute by that
+    name)!  By default, the name that must be appended to the URL should
+    simply be the same as the name of the attribute; but by providing a
+    `name` keyword argument, the programmer can designate another name
+    to appear in the URL instead of the raw attribute name.
+
+    """
     scope = martian.CLASS
     store = martian.DICT
 
@@ -117,6 +207,14 @@
         return (name, attr)
 
 class restskin(martian.Directive):
+    """The `grok.restskin()` directive.
+
+    This directive is placed inside of `grok.IRESTLayer` subclasses to
+    indicate what their layer name will be within a REST URL.  Giving
+    the skin ``grok.restskin('b')``, for example, will enable URLs that
+    look something like `http://localhost/++rest++b/app`.
+
+    """
     # We cannot do any better than to check for a class scope. Ideally we
     # would've checked whether the context is indeed an Interface class.
     scope = martian.CLASS