[Checkins] SVN: Sandbox/ulif/grok-reference-with-rest/doc/reference/directives.rst Added reference docs.

[Uli Fouquet]

Log message for revision 80179:
  Added reference docs.

Changed:
  U   Sandbox/ulif/grok-reference-with-rest/doc/reference/directives.rst

-=-
Modified: Sandbox/ulif/grok-reference-with-rest/doc/reference/directives.rst
===================================================================
--- Sandbox/ulif/grok-reference-with-rest/doc/reference/directives.rst	2007-09-27 02:59:14 UTC (rev 80178)
+++ Sandbox/ulif/grok-reference-with-rest/doc/reference/directives.rst	2007-09-27 03:23:32 UTC (rev 80179)
@@ -223,7 +223,8 @@
 .. function:: grok.implements(*interfaces)
 
    A class level directive to declare one or more `interfaces`, as
-   implementers of the surrounding class.
+   implementers of the surrounding class. This directive allows
+   several parameters.
 
    :func:`grok.implements` is currently an alias for 
    :func:`zope.interface.implements`.
@@ -362,28 +363,106 @@
       :func:`grok.implements`
 
 
-:func:`grok.name`
-=================
+:func:`grok.name` -- associate a component with a name
+======================================================
 
 
-.. function:: grok.name(*arg)
+.. function:: grok.name(name)
 
-   foobar
+   A class level directive used to associate a component with a single
+   name `name`. Typically this directive is optional. The default behaviour
+   when no name is given depends on the component. The same applies to
+   the semantics of this directive: for what exactly a name is set
+   when using this directive, depends on the component.
 
-   Used to associate a component with a name. Typically this directive
-   is optional. The default behaviour when no name is given depends on
-   the component.
+   **Example:** ::
 
+      import grok
 
-:func:`grok.local_utility`
-==========================
+      class Mammoth(grok.Model):
+         pass
 
+      class Index(grok.View):
+         grok.name('index')
 
-.. function:: grok.local_utility(*arg)
 
-   foobar
+   .. seealso::
 
+      :class:`grok.Adapter`, :class:`grok.Annotation`,
+      :class:`grok.GlobalUtility`, :class:`grok.Indexes`, 
+      :class:`grok.MultiAdapter`, :class:`grok.Role`, 
+      :class:`grok.View`
 
+
+
+
+:func:`grok.local_utility` -- register a local utility
+======================================================
+
+
+.. function:: grok.local_utility(factory[, provides=None[, name=u''[, setup=None[, public=False[, name_in_container=None]]]]])
+
+   A class level directive to register a local utility.
+
+   `factory` -- the factory that creates the utility.
+
+   `provides` -- the interface the utility should be looked up with.
+
+   `name` -- the name of the utility.
+
+   `setup` -- a callable that receives the utility as its single
+      argument, it is called after the utility has been created and
+      stored.
+
+   `public` -- if `False`, the utility will be stored below
+      `++etc++site`.  If `True`, the utility will be stored directly
+      in the site.  The site should in this case be a container.
+
+   `name_in_container` -- the name to use for storing the utility.
+
+   All but the first parameter are optional. 
+
+   To register a local utility correctly, Grok must know about the
+   interface, the utility should be looked up with. If none is given,
+   Grok looks up any interfaces implemented by instances delivered by
+   `factory` and if exactly one can be found, it is taken. See
+   :func:`grok.global_utility`.
+
+   Every single combination of interfaces and names can only be
+   registered once per module.
+
+   It is not possible to declare a local utility as public, if the
+   site is not a container. Grok will remind you of this. To store a
+   utility in a container, a `name_in_container` is needed. If
+   none is given, Grok will make up one automatically.
+
+   An alternative way to define a local utility is to subclass from
+   :class:`grok.LocalUtility`.
+
+   **Example:**
+
+      The following code registers a local unnamed utility `fireplace` in
+      instances of :class:`Cave` ::
+
+         import grok
+         from zope import interface
+
+         class IFireplace(interface.Interface):
+             pass
+
+         class Fireplace(grok.LocalUtility):
+             grok.implements(IFireplace)
+
+         class Cave(grok.Container, grok.Site):
+             grok.local_utility(Fireplace, public=True, 
+                                name_in_container='fireplace')
+      
+
+   .. seealso::
+
+      :func:`grok.global_utility`, :class:`grok.LocalUtility`
+
+
 :func:`grok.provides`
 =====================
 
@@ -476,3 +555,12 @@
 
    foobar
 
+
+:func:`grok.title`
+========================
+
+
+.. function:: grok.title(*arg)
+
+   foobar
+