# HG changeset patch
# User cmlenz
# Date 1133017210 0
# Node ID 87c9b1e8f0860e32393fc8d430ecdedc63cd2257
# Parent  a8fd83c0317d86e34c97ca567c34bc5cdd8a03db
More docstring improvements.

diff --git a/bitten/model.py b/bitten/model.py
--- a/bitten/model.py
+++ b/bitten/model.py
@@ -7,6 +7,8 @@
 # you should have received as part of this distribution. The terms
 # are also available at http://bitten.cmlenz.net/wiki/License.
 
+"""Model classes for objects persisted in the database."""
+
 try:
     set
 except NameError:
@@ -44,7 +46,8 @@
         self.label = label or ''
         self.description = description or ''
 
-    exists = property(fget=lambda self: self._old_name is not None)
+    exists = property(fget=lambda self: self._old_name is not None,
+                      doc='Whether this configuration exists in the database')
 
     def delete(self, db=None):
         """Remove a build configuration and all dependent objects from the
@@ -198,7 +201,8 @@
         self.name = name
         self.rules = []
 
-    exists = property(fget=lambda self: self.id is not None)
+    exists = property(fget=lambda self: self.id is not None,
+                      doc='Whether this target platform exists in the database')
 
     def delete(self, db=None):
         """Remove the target platform from the database."""
@@ -361,9 +365,12 @@
         self.status = status
         self.slave_info = {}
 
-    exists = property(fget=lambda self: self.id is not None)
-    completed = property(fget=lambda self: self.status != Build.IN_PROGRESS)
-    successful = property(fget=lambda self: self.status == Build.SUCCESS)
+    exists = property(fget=lambda self: self.id is not None,
+                      doc='Whether this build exists in the database')
+    completed = property(fget=lambda self: self.status != Build.IN_PROGRESS,
+                         doc='Whether the build has been completed')
+    successful = property(fget=lambda self: self.status == Build.SUCCESS,
+                          doc='Whether the build was successful')
 
     def delete(self, db=None):
         """Remove the build from the database."""
@@ -537,8 +544,10 @@
         self.errors = []
         self._exists = False
 
-    exists = property(fget=lambda self: self._exists)
-    successful = property(fget=lambda self: self.status == BuildStep.SUCCESS)
+    exists = property(fget=lambda self: self._exists,
+                      doc='Whether this build step exists in the database')
+    successful = property(fget=lambda self: self.status == BuildStep.SUCCESS,
+                          doc='Whether the build step was successful')
 
     def delete(self, db=None):
         """Remove the build step from the database."""
@@ -682,7 +691,8 @@
         self.orderno = orderno and int(orderno) or 0
         self.messages = []
 
-    exists = property(fget=lambda self: self.id is not None)
+    exists = property(fget=lambda self: self.id is not None,
+                      doc='Whether this build log exists in the database')
 
     def delete(self, db=None):
         """Remove the build log from the database."""
@@ -805,7 +815,8 @@
         self.generator = generator or ''
         self.items = []
 
-    exists = property(fget=lambda self: self.id is not None)
+    exists = property(fget=lambda self: self.id is not None,
+                      doc='Whether this report exists in the database')
 
     def delete(self, db=None):
         """Remove the report from the database."""
diff --git a/bitten/queue.py b/bitten/queue.py
--- a/bitten/queue.py
+++ b/bitten/queue.py
@@ -32,12 +32,13 @@
     """Collect all changes for a build configuration that either have already
     been built, or still need to be built.
     
-    This function is a generator that yields `(platform, rev, build)` tuples,
-    where `platform` is a `TargetPlatform` object, `rev` is the identifier of
-    the changeset, and `build` is a `Build` object or `None`.
+    This function is a generator that yields C{(platform, rev, build)} tuples,
+    where C{platform} is a L{bitten.model.TargetPlatform} object, C{rev} is the
+    identifier of the changeset, and C{build} is a L{bitten.model.Build} object
+    or C{None}.
 
-    @param repos: The version control repository
-    @param config: The build configuration
+    @param repos: the version control repository
+    @param config: the build configuration
     @param db: a database connection (optional)
     """
     env = config.env
@@ -91,7 +92,7 @@
     def __init__(self, env):
         """Create the build queue.
         
-        @param env: The Trac environment
+        @param env: the Trac environment
         """
         self.env = env
         self.slaves = {} # Sets of slave names keyed by target platform ID
@@ -109,9 +110,9 @@
         """Check whether one of the pending builds can be built by one of the
         available build slaves.
         
-        If such a build is found, this method returns a `(build, slave)` tuple,
-        where `build` is the `Build` object and `slave` is the name of the
-        build slave.
+        If such a build is found, this method returns a C{(build, slave)}
+        tuple, where C{build} is the L{bitten.model.Build} object and C{slave}
+        is the name of the build slave that should handle the build.
 
         Otherwise, this function will return C{(None, None)}
         """
@@ -228,7 +229,7 @@
         """Unregister a build slave.
         
         This method removes the slave from the registry, and also resets any
-        in-progress builds by this slave to `PENDING` state.
+        in-progress builds by this slave to PENDING state.
         
         @param name: The name of the slave
         @return: C{True} if the slave was registered for this build queue,
diff --git a/bitten/snapshot.py b/bitten/snapshot.py
--- a/bitten/snapshot.py
+++ b/bitten/snapshot.py
@@ -12,7 +12,7 @@
 Snapshots of the code base are stored in the Trac environment as tar archives,
 compressed using bzip2.
 
-These files use the naming convention `[config_name]_r[revision].tar.bz2` so
+These files use the naming convention C{[config_name]_r[revision].tar.bz2} so
 they can be located programmatically after creation, and associated with the
 build config and revision they apply to.
 
@@ -45,6 +45,8 @@
 
 from bitten.util import md5sum
 
+__all__ = ['SnapshotManager']
+
 log = logging.getLogger('bitten.snapshot')
 
 MAX_SNAPSHOTS = 10
@@ -57,7 +59,8 @@
     def __init__(self, config):
         """Create the snapshot manager.
         
-        @param config: The `BuildConfig` instance
+        @param config: the build configuration
+        @type config: an instance of L{bitten.model.BuildConfig}
         """
         assert config and config.exists, 'Build configuration does not exist'
         self.env = config.env
@@ -111,7 +114,11 @@
             yield mtime, rev, filepath
 
     def _cleanup(self, limit=None):
-        """Remove obsolete snapshots to preserve disk space."""
+        """Remove obsolete snapshots to preserve disk space.
+        
+        @param limit: the maximum number of snapshot archives to keep; defaults
+            to the value of the C{max_snapshots} value in C{trac.ini}.
+        """
         self._lock.acquire()
         try:
             self._index.sort(lambda a, b: -cmp(a[0], b[0]))
@@ -137,6 +144,9 @@
         The archive is created in a worker thread. The return value of this
         function is the thread object. The caller may use this object to check
         for completion of the operation.
+        
+        @param rev: the repository revision for which a snapshot archive should
+            be created
         """
         self._lock.acquire()
         try:
@@ -179,7 +189,7 @@
                 base_filepath=None, base_prefix=None):
         """Actually create a snapshot archive.
         
-        This is used internally from the `create()` function and executed in a
+        This is used internally from the C{create()} function and executed in a
         worker thread.
         """
         log.debug('Preparing snapshot archive for %s@%s', new_root.path,
@@ -260,7 +270,10 @@
         """Returns the path to an already existing snapshot archive for the
         specified revision.
         
-        If no snapshot exists for the revision, this function returns `None`.
+        If no snapshot exists for the revision, this function returns C{None}.
+        
+        @param rev: the repository revision for which a snapshot archive should
+            be retrieved
         """
         self._lock.acquire()
         try:
diff --git a/bitten/trac_ext/__init__.py b/bitten/trac_ext/__init__.py
--- a/bitten/trac_ext/__init__.py
+++ b/bitten/trac_ext/__init__.py
@@ -7,4 +7,6 @@
 # you should have received as part of this distribution. The terms
 # are also available at http://bitten.cmlenz.net/wiki/License.
 
+"""Implementation of the Bitten plugin for Trac."""
+
 from bitten.trac_ext.api import *
diff --git a/bitten/trac_ext/api.py b/bitten/trac_ext/api.py
--- a/bitten/trac_ext/api.py
+++ b/bitten/trac_ext/api.py
@@ -7,6 +7,8 @@
 # you should have received as part of this distribution. The terms
 # are also available at http://bitten.cmlenz.net/wiki/License.
 
+"""Interfaces of extension points provided by the Bitten Trac plugin."""
+
 from trac.core import *
 
 
@@ -14,25 +16,30 @@
     """Extension point interface for components that need to be notified of
     build events.
     
-    Note that these will be notified in the process running the build master."""
+    Note that these will be notified in the process running the build master,
+    not the web interface.
+    """
 
     def build_started(build):
         """Called when a build slave has accepted a build initiation.
         
-        @param build: The `bitten.model.Build` instance representing the build
+        @param build: the build that was started
+        @type build: an instance of L{bitten.model.Build}
         """
 
-    def build_aborted(config, build):
+    def build_aborted(build):
         """Called when a build slave cancels a build or disconnects.
         
-        @param build: The `bitten.model.Build` instance representing the build
+        @param build: the build that was aborted
+        @type build: an instance of L{bitten.model.Build}
         """
 
-    def build_completed(config, build):
+    def build_completed(build):
         """Called when a build slave has completed a build, regardless of the
         outcome.
         
-        @param build: The `bitten.model.Build` instance representing the build
+        @param build: the build that was aborted
+        @type build: an instance of L{bitten.model.Build}
         """
 
 
@@ -43,8 +50,14 @@
     def get_formatter(req, build):
         """Return a function that gets called for every log message.
         
-        The function must take four positional arguments, `step`, `generator`,
-        `level` and `message`, and return the formatted message.
+        The function must take four positional arguments, C{step},
+        C{generator}, C{level} and C{message}, and return the formatted
+        message as a string.
+
+        @param req: the request object
+        @param build: the build to which the logs belong that should be
+            formatted
+        @type build: an instance of L{bitten.model.Build}
         """
 
 
@@ -58,7 +71,17 @@
 
     def render_summary(req, config, build, step, category):
         """Render a summary for the given report and return the results HTML as
-        a string."""
+        a string.
+        
+        @param req: the request object
+        @param config: the build configuration
+        @type config: an instance of L{bitten.model.BuildConfig}
+        @param build: the build
+        @type build: an instance of L{bitten.model.Build}
+        @param step: the build step
+        @type step: an instance of L{bitten.model.BuildStep}
+        @param category: the category of the report that should be summarized
+        """
 
 
 class IReportChartGenerator(Interface):
@@ -70,7 +93,13 @@
         component supports."""
 
     def generate_chart_data(req, config, category):
-        """Generate the data for the chart.
+        """Generate the data for a report chart.
         
         This method should store the data in the HDF of the request and return
-        the name of the template that should process the data."""
+        the name of the template that should process the data.
+        
+        @param req: the request object
+        @param config: the build configuration
+        @type config: an instance of L{bitten.model.BuildConfig}
+        @param category: the category of reports to include in the chart
+        """
diff --git a/bitten/trac_ext/web_ui.py b/bitten/trac_ext/web_ui.py
--- a/bitten/trac_ext/web_ui.py
+++ b/bitten/trac_ext/web_ui.py
@@ -7,6 +7,8 @@
 # you should have received as part of this distribution. The terms
 # are also available at http://bitten.cmlenz.net/wiki/License.
 
+"""Implementation of the Bitten web interface."""
+
 from datetime import datetime
 import posixpath
 import re
@@ -68,9 +70,11 @@
     # ITemplatesProvider methods
 
     def get_htdocs_dirs(self):
+        """Return the directories containing static resources."""
         return [('bitten', pkg_resources.resource_filename(__name__, 'htdocs'))]
 
     def get_templates_dirs(self):
+        """Return the directories containing templates."""
         return [pkg_resources.resource_filename(__name__, 'templates')]
 
 
@@ -82,9 +86,16 @@
     # INavigationContributor methods
 
     def get_active_navigation_item(self, req):
+        """Called by Trac to determine which navigation item should be marked
+        as active.
+        
+        @param req: the request object
+        """
         return 'build'
 
     def get_navigation_items(self, req):
+        """Return the navigation item for access the build status overview from
+        the Trac navigation bar."""
         if not req.perm.has_permission('BUILD_VIEW'):
             return
         yield 'mainnav', 'build', \
diff --git a/bitten/upgrades.py b/bitten/upgrades.py
--- a/bitten/upgrades.py
+++ b/bitten/upgrades.py
@@ -7,6 +7,9 @@
 # you should have received as part of this distribution. The terms
 # are also available at http://bitten.cmlenz.net/wiki/License.
 
+"""Automated upgrades for the Bitten database tables, and other data stored
+in the Trac environment."""
+
 import os
 import sys
 
diff --git a/bitten/util/__init__.py b/bitten/util/__init__.py
--- a/bitten/util/__init__.py
+++ b/bitten/util/__init__.py
@@ -8,3 +8,9 @@
 # This software is licensed as described in the file COPYING, which
 # you should have received as part of this distribution. The terms
 # are also available at http://bitten.cmlenz.net/wiki/License.
+
+"""Generic utility functions and classes.
+
+Functionality in these modules have no dependencies on modules outside of this
+package, so that they could theoretically be used in other projects.
+"""
diff --git a/bitten/util/loc.py b/bitten/util/loc.py
--- a/bitten/util/loc.py
+++ b/bitten/util/loc.py
@@ -1,4 +1,5 @@
-#!/usr/bin/env python
+# -*- coding: iso8859-1 -*-
+#
 # Copyright (C) 1998 Dinu C. Gherman <gherman@europemail.com>
 # Copyright (C) 2005 Christopher Lenz <cmlenz@gmx.de>
 # 
@@ -16,6 +17,8 @@
 #     that copyright notice and this  permission notice appear in
 #     supporting documentation.
 
+"""Support for counting the lines of code in Python programs."""
+
 import re
 
 # Reg. exps. to find the end of a triple quote, given that
@@ -58,11 +61,14 @@
 BLANK, CODE, COMMENT, DOC  = 0, 1, 2, 3
 
 def count(source):
-    """Parse the given file-like object.
+    """Parse the given file-like object as Python source code.
     
-    For every line, returns a `(lineno, type, line)` tuple, where `lineno`
-    is the line number (starting at 0), `type` is one of `BLANK`, `CODE,
-    `COMMENT` or `DOC`, and `line` is the actual content of the line."""
+    For every line, return a C{(lineno, type, line)} tuple, where C{lineno}
+    is the line number (starting at 0), C{type} is one of C{BLANK}, C{CODE},
+    C{COMMENT} or C{DOC}, and C{line} is the actual content of the line.
+
+    @param source: a file-like object containing Python code
+    """
 
     quote3_finder = {'"': _dquote3_finder, "'": _squote3_finder}
     quote1_finder = {'"': _dquote1_finder, "'": _squote1_finder }
diff --git a/bitten/util/xmlio.py b/bitten/util/xmlio.py
--- a/bitten/util/xmlio.py
+++ b/bitten/util/xmlio.py
@@ -252,8 +252,10 @@
         self._node = node
         self.attr = ParsedElement._Attrs(node)
 
-    name = property(fget=lambda self: self._node.localName)
-    namespace = property(fget=lambda self: self._node.namespaceURI)
+    name = property(fget=lambda self: self._node.localName,
+                    doc='Local name of the element')
+    namespace = property(fget=lambda self: self._node.namespaceURI,
+                         doc='Namespace URI of the element')
 
     def children(self, name=None):
         """Iterate over the child elements of this element.