Update various docstrings.

src/grok/components.py

@@ -48,12 +48,13 @@
 class Application(grokcore.site.Site):
     """Mixin for creating Grok application objects.
 
-    When a `grok.Container` (or a `grok.Model`, though most developers
-    use containers) also inherits from `grok.Application`, it not only
-    gains the component registration abilities of a `grok.Site`, but
-    will also be listed in the Grok admin control panel as one of the
-    applications that the admin can install directly at the root of
-    their Zope database.
+    When a :class:`grok.Container` (or a :class:`grok.Model`, though
+    most developers use containers) also inherits from
+    :class:`grok.Application`, it not only gains the component
+    registration abilities of a :class:`grok.Site`, but will also be
+    listed in the Grok admin control panel as one of the applications
+    that the admin can install directly at the root of their Zope
+    database.
 
     """
     interface.implements(grokcore.site.interfaces.IApplication)
@@ -62,6 +63,9 @@ class Application(grokcore.site.Site):
 class View(grokcore.view.View):
     """The base class for views with templates in Grok applications.
 
+    Implements the :class:`grokcore.view.interfaces.IGrokView`
+    interface.
+    
     Each class that inherits from `grok.View` is designed to "render" a
     category of content objects by reducing them to a document (often an
     HTML document).  Every view has a name, and is invoked when users
@@ -132,7 +136,10 @@ class ``MammothList`` occurs in a module ``<src>/animal.py``, for
     interface.implements(interfaces.IGrokView)
 
     def application_url(self, name=None, data=None):
-        """Return the URL of the nearest enclosing `grok.Application`."""
+        """Return the URL of the closest :class:`grok.Application` object in
+        the hierarchy or the URL of a named object (``name``
+        parameter) relative to the closest application object.
+        """
         return util.application_url(self.request, self.context, name, data)
 
     def flash(self, message, type='message'):
@@ -308,32 +315,37 @@ def traverse(self, name):
 class IndexesClass(object):
     """Base class for index collections in a Grok application.
 
-    A `grok.Indexes` utility provides one or more Zope Database content
-    indexes for use in a `grok.Site` or `grok.Application`.  The site or
-    application that the indexes are intended for should be named with
-    the `grok.site()` directive, and the kind of object to index should
-    be named with a `grok.context()` directive.
+    A `grok.Indexes` utility provides one or more Zope Database
+    content indexes for use in a :class:`grok.Site` or
+    :class:`grok.Application`.  The site or application that the
+    indexes are intended for should be named with the :func:`grok.site()`
+    directive, and the kind of object to index should be named with a
+    :func:`grok.context()` directive.
 
     Inside their class, the developer should specify one or more
-    `grok.index.Field` instances naming object attributes that should be
-    indexed (and therefore searchable)::
-
+    :class:`grok.index.Field`, :class:`grok.index.Text`, or
+    :class:`grok.index.Set` instances naming object attributes that
+    should be indexed (and therefore searchable).::
+    
         class ArticleIndex(grok.Indexes):
             grok.site(Newspaper)
             grok.context(Article)
             author = index.Field()
             title = index.Field()
             body = index.Text()
 
-    See the `grok.index` module for more information on field types.
-
-    Note that indexes are persistent: they are stored in the Zope
-    database alongside the site or application that they index.  They
-    are created when the site or application is first created, and so an
-    already-created site will not change just because the definition of
-    one of its `grok.Indexes` changes; it will either have to be deleted
-    and re-created, or some other operation performed to bring its
-    indexes up to date.
+    See the :mod:`grok.index` module for more information on field
+    types.
+
+    .. note:: Indexes are persistent: they are stored in the Zope
+              database alongside the site or application that they
+              index.  They are created when the site or application is
+              first created (and made persistent), and so an
+              already-created site will not change just because the
+              definition of one of its :data:`grok.Indexes` changes;
+              it will either have to be deleted and re-created, or
+              some other operation performed to bring its indexes up
+              to date.
 
     """
     def __init__(self, name, bases=(), attrs=None):

src/grok/index.py

@@ -29,24 +29,27 @@
 
 
 class IndexDefinition(object):
-    """The definition of a particular index in a `grok.Indexes` class.
+    """The definition of a particular index in a :data:`grok.Indexes`
+    class.
 
-    This base class defines the actual behavior of `grok.index.Field`
-    and the other kinds of attribute index that Grok supports.  Upon our
-    instantiation, we save every parameter that we were passed; later,
-    if an index actually needs to be created (which is typically at the
-    moment when a new `grok.Application` object is added to the Zope
-    Database), then our `setup()` method gets called.
+    This base class defines the actual behavior of
+    :class:`grok.index.Field` and the other kinds of attribute index
+    that Grok supports.  Upon our instantiation, we save every
+    parameter that we were passed; later, if an index actually needs
+    to be created (which is typically at the moment when a new
+    :class:`grok.Application` object is added to the Zope Database),
+    then our :meth:`setup()` method gets called.
 
     The only parameter that is actually significant to us is `attribute`
     which (optionally) defines the attribute we should index.  All other
     parameters are simply passed along to the Zope index we create,
     which interprets them as configuration details of its own.
 
-    Note that, since index creation (and thus a call to our `setup()`
-    method) currently occurs only during the creation of a new Grok
-    `Application` object in the Zope Database, the presence of this
-    declaration in Grok application code is nearly always a no-op.
+    Note that, since index creation (and thus a call to our
+    :meth:`setup()` method) currently occurs only during the creation
+    of a new Grok `Application` object in the Zope Database, the
+    presence of this declaration in Grok application code is nearly
+    always a no-op.
 
     """
     implements(IIndexDefinition)
@@ -91,15 +94,16 @@ def setup(self, catalog, name, context, module_info):
 
 
 class Field(IndexDefinition):
-    """A `grok.Indexes` index that matches against an entire field."""
+    """A :class:`grok.Indexes` index that matches against an entire field."""
     index_class = FieldIndex
 
 
 class Text(IndexDefinition):
-    """A `grok.Indexes` index supporting full-text searches of a field."""
+    """A :class:`grok.Indexes` index supporting full-text searches of a
+    field."""
     index_class = TextIndex
 
 
 class Set(IndexDefinition):
-    """A `grok.Indexes` index supporting keyword searches of a field."""
+    """A :class:`grok.Indexes` index supporting keyword searches of a field."""
     index_class = SetIndex