=== modified file 'lava_server/bread_crumbs.py'
--- lava_server/bread_crumbs.py	2011-09-30 13:34:25 +0000
+++ lava_server/bread_crumbs.py	2011-10-03 14:07:55 +0000
@@ -18,7 +18,30 @@
 
 
 """
-Bread crubm management for LAVA server
+Bread crumb management for LAVA server.
+
+This system allows one to construct static trees of views (come to think about
+it it could also be used as a site map generator) where each view has at most
+one parent. In such model any view could be followed back through the parent
+link to create a bread crumb trail of named URLs.
+
+It is important to emphasise that this system is STATIC, that is, it is not
+based on browsing history. Regardless on how the user got to a particular view
+the bread crumb system will report the same set of pages. The idea is not to
+let users go back (that's the what the browser allows them to do) but to put
+the current page into context of where it "belongs".
+
+To use this system apply the @BreadCrumb(name, parent=parent_view,
+needs=['required', 'keywords']) decorator to your view function. To render
+breadcrumbs you can use the default template that is a part of
+"layout/content.html" template. Your context must include the bread_crumb_trail
+variable. To construct it call BreadCrumbTrail.leading_to(your_view_name, ...)
+passing any of  the keyword arguments specified in needs of your and any parent
+views (yes this is annoying).
+
+A mistake in paring 'needs' to keywords passed to BreadCrumbTrail.leading_to()
+will result in logged warnings (either a name of the URL being not
+constructible). To fix that simply add the missing keyword argument and reload.
 """
 
 from django.core.urlresolvers import reverse
@@ -26,8 +49,23 @@
 
 
 class BreadCrumb(object):
+    """
+    A crumb of bread left in the forest of pages to let you go back to (no, not
+    to where you came from) where the developer desired you to go.
+    """
 
     def __init__(self, name, parent=None, needs=None):
+        """
+        Construct a bread crumb object.
+
+        The name is the essential property creating the actual text visible on
+        web pages. It may be a static string or a new-style python string
+        template. Parent allows one to construct a static brad crumb tree where
+        each crubm may have at most one parent. Needs, if specified, must be
+        an array of strings that denote identifiers required to resolve the URL
+        of this bread crumb. The identifiers are obtained from the call
+        BreadCrumbTrail.leading_to().
+        """
         self.name = name
         self.view = None
         self.parent = parent
@@ -38,11 +76,23 @@
             self.name, self.view, self.parent)
 
     def __call__(self, view):
+        """
+        Call method, used when decorating function-based views
+
+        Id does not redefine the function (so is not a real decorator) but
+        instead stores the bradcrubm object in the _bread_crumb attribute of
+        the function.
+        """
         self.view = view
         view._bread_crumb = self
         return view
 
     def get_name(self, kwargs):
+        """
+        Get the name of this crumb.
+
+        The name is formatted with the specfied keyword argments.
+        """
         try:
             return self.name.format(**kwargs)
         except:
@@ -50,6 +100,14 @@
             raise
 
     def get_absolute_url(self, kwargs):
+        """
+        Get the URL of this crumb.
+
+        The URL is constructed with a call to dajngo's reverse() function. It
+        is supplemented with the same variables that were listed in needs array
+        in the bread crumb constructor. The arguments are passed in order, from
+        the kwargs dictionary.
+        """
         try:
             return reverse(self.view, args=[kwargs[name] for name in self.needs])
         except:
@@ -58,6 +116,16 @@
 
 
 class LiveBreadCrumb(object):
+    """
+    Bread crumb instance as observed by a particular request.
+
+    It is a binding between the global view-specific bread crumb object and
+    dynamic request-specific keyword arguments.
+
+    For convenience it provides two bread crumb functions (get_name() and
+    get_absolute_url()) that automatically provide the correct keyword
+    arguments.
+    """
 
     def __init__(self, bread_crumb, kwargs):
         self.bread_crumb = bread_crumb
@@ -71,6 +139,11 @@
 
 
 class BreadCrumbTrail(object):
+    """
+    A list of live bread crumbs that lead from a particular view, along the
+    parent chain, all the way to the root view (that is without any parent
+    view).
+    """
 
     def __init__(self, bread_crumb_list, kwargs):
         self.bread_crumb_list = bread_crumb_list
@@ -82,6 +155,16 @@
 
     @classmethod
     def leading_to(cls, view, **kwargs):
+        """
+        Create an instance of BreadCrumbTrail that starts at the specified view.
+
+        Additional keyword arguments, if provided, will be available to
+        get_name() and get_absolute_url() of each LiveBreadCrumb that makes up
+        this trail. In practice they should contain a set of arguments that are
+        needed by any parent bread crumb URL or name.
+
+        TODO: could we check this statically somehow?
+        """
         lst = []
         while view is not None:
             lst.append(view._bread_crumb)

