From 1f7fcec9352691a6e7a90c20e13dc59b65865030 Mon Sep 17 00:00:00 2001
From: Ned Batchelder <ned@nedbatchelder.com>
Date: Sat, 9 May 2009 20:46:58 -0400
Subject: More docstrings all around.

---
 coverage/__init__.py | 12 ++++++++++--
 coverage/html.py     | 22 ++++++++++++++++------
 coverage/misc.py     |  1 +
 coverage/templite.py | 38 +++++++++++++++++++++++++++++++++-----
 4 files changed, 60 insertions(+), 13 deletions(-)

(limited to 'coverage')

diff --git a/coverage/__init__.py b/coverage/__init__.py
index c1b95874..c787b341 100644
--- a/coverage/__init__.py
+++ b/coverage/__init__.py
@@ -23,12 +23,20 @@ from coverage.misc import CoverageException
 _the_coverage = None
 
 def _singleton_method(name):
-    def func(*args, **kwargs):
+    """Return a function to the `name` method on a singleton `coverage` object.
+    
+    The singleton object is created the first time one of these functions is
+    called.
+    
+    """
+    def wrapper(*args, **kwargs):
+        """Singleton wrapper around a coverage method."""
         global _the_coverage
         if not _the_coverage:
             _the_coverage = coverage()
         return getattr(_the_coverage, name)(*args, **kwargs)
-    return func
+    return wrapper
+
 
 # Define the module-level functions.
 use_cache = _singleton_method('use_cache')
diff --git a/coverage/html.py b/coverage/html.py
index 6fc49ff5..d8f98c45 100644
--- a/coverage/html.py
+++ b/coverage/html.py
@@ -16,9 +16,7 @@ def data(fname):
     
 
 class HtmlReporter(Reporter):
-    """HTML reporting.
-    
-    """
+    """HTML reporting."""
     
     def __init__(self, coverage, ignore_errors=False):
         super(HtmlReporter, self).__init__(coverage, ignore_errors)
@@ -27,7 +25,14 @@ class HtmlReporter(Reporter):
         
         self.files = []
 
-    def report(self, morfs, directory=None, omit_prefixes=None):
+    def report(self, morfs, directory, omit_prefixes=None):
+        """Generate an HTML report for `morfs`.
+        
+        `morfs` is a list of modules or filenames.  `directory` is where to put
+        the HTML files. `omit_prefixes` is a list of strings, prefixes of
+        modules to omit from the report.
+        
+        """
         assert directory, "must provide a directory for html reporting"
         
         # Process all the files.
@@ -147,10 +152,15 @@ def not_empty(t):
     return t or "&nbsp;"
     
 def format_pct(p):
+    """Format a percentage value for the HTML reports."""
     return "%.0f" % p
 
 def spaceless(html):
-    """Squeeze out some of that annoying extra space that comes from
-    nicely-formatted templates."""
+    """Squeeze out some annoying extra space from an HTML string.
+    
+    Nicely-formatted templates mean lots of extra space in the result.  Get
+    rid of some.
+    
+    """
     html = re.sub(">\s+<p ", ">\n<p ", html)
     return html
diff --git a/coverage/misc.py b/coverage/misc.py
index 398f9b27..8a8b5117 100644
--- a/coverage/misc.py
+++ b/coverage/misc.py
@@ -47,4 +47,5 @@ def format_lines(statements, lines):
 
 
 class CoverageException(Exception):
+    """An exception specific to Coverage."""
     pass
diff --git a/coverage/templite.py b/coverage/templite.py
index f75e2a2d..fabc3dbb 100644
--- a/coverage/templite.py
+++ b/coverage/templite.py
@@ -8,9 +8,26 @@ import re
 
 class Templite(object):
     """A simple template renderer, for a nano-subset of Django syntax.
+
+    Supported constructs are extended variable access::
+    
+        {{var.modifer.modifier|filter|filter}}
+        
+    and loops::
+    
+        {% for var in list %}...{% endfor %}
+    
+    Construct a Templite with the template text, then use `render` against a
+    dictionary context to create a finished string.
     
     """
     def __init__(self, text, *contexts):
+        """Construct a Templite with the given `text`.
+        
+        `contexts` are dictionaries of values to use for future renderings.
+        These are good for filters and global values.
+        
+        """
         self.loops = []
         self.text = self._prepare(text)
         self.context = {}
@@ -18,12 +35,17 @@ class Templite(object):
             self.context.update(context)
 
     def render(self, context=None):
+        """Render this template by applying it to `context`.
+        
+        `context` is a dictionary of values to use in this rendering.
+        
+        """
         # Make the complete context we'll use.
         ctx = dict(self.context)
         if context:
             ctx.update(context)
             
-        ctxaccess = ContextAccess(ctx)
+        ctxaccess = _ContextAccess(ctx)
         
         # Render the loops.
         for iloop, (loopvar, listvar, loopbody) in enumerate(self.loops):
@@ -41,7 +63,7 @@ class Templite(object):
         # Pull out loops.
         text = re.sub(
             r"(?s){% for ([a-z0-9_]+) in ([a-z0-9_.|]+) %}(.*?){% endfor %}",
-            self._loop_repl, text
+            self._loop_prepare, text
             )
         # Protect actual percent signs in the text.
         text = text.replace("%", "%%")
@@ -49,7 +71,8 @@ class Templite(object):
         text = re.sub(r"{{([^}]+)}}", r"%(\1)s", text)
         return text
 
-    def _loop_repl(self, match):
+    def _loop_prepare(self, match):
+        """Prepare a loop body for `_prepare`."""
         nloop = len(self.loops)
         # Append (loopvar, listvar, loopbody) to self.loops
         loopvar, listvar, loopbody = match.groups()
@@ -58,8 +81,13 @@ class Templite(object):
         return "{{loop:%d}}" % nloop
 
 
-class ContextAccess(object):
+class _ContextAccess(object):
+    """A mediator for a context.
     
+    Implements __getitem__ on a context for Templite, so that string formatting
+    references can pull data from the context.
+    
+    """
     def __init__(self, context):
         self.context = context
 
@@ -70,7 +98,7 @@ class ContextAccess(object):
             for func in pipes[1:]:
                 value = self[func](value)
         elif "." in key:
-            dots = key.split('.') 
+            dots = key.split('.')
             value = self[dots[0]]
             for dot in dots[1:]:
                 try:
-- 
cgit v1.2.1