some more docstrings and I'm ready to go live

3 files changed, 55 insertions, 18 deletions

diff --git a/doc/build/unicode.rst b/doc/build/unicode.rst
index 771ca4b..cc80733 100644
--- a/doc/build/unicode.rst
+++ b/doc/build/unicode.rst
@@ -260,6 +260,8 @@ dumbed-down version of ``StringIO`` that gathers all strings into
 a list and uses ``u''.join(elements)`` to produce the final output
 - its markedly faster than ``StringIO``.
 
+.. _unicode_disabled:
+
 Saying to Heck with it: Disabling the usage of Unicode entirely
 ================================================================
 
diff --git a/doc/build/usage.rst b/doc/build/usage.rst
index 4309c8c..06067a2 100644
--- a/doc/build/usage.rst
+++ b/doc/build/usage.rst
@@ -83,6 +83,8 @@ source code for the module. The next time a :class:`.Template` with the
 same arguments is created, this module file will be
 automatically re-used.
 
+.. _usage_templatelookup:
+
 Using TemplateLookup
 ====================
 
@@ -171,6 +173,8 @@ production system, setting ``filesystem_checks`` to ``False`` can
 afford a small to moderate performance increase (depending on
 the type of filesystem used).
 
+.. _usage_unicode:
+
 Using Unicode and Encoding
 ===========================
 
diff --git a/mako/template.py b/mako/template.py
index 9a6c6c2..0e286f9 100644
--- a/mako/template.py
+++ b/mako/template.py
@@ -32,23 +32,41 @@ class Template(object):
     :param filename: filename of the source template.  This argument is 
      mutually exclusive versus the "text" parameter.
 
-    :param buffer_filters:
+    :param buffer_filters: string list of filters to be applied
+     to the output of %defs which are buffered, cached, or otherwise
+     filtered, after all filters
+     defined with the %def itself have been applied. Allows the
+     creation of default expression filters that let the output
+     of return-valued %defs "opt out" of that filtering via
+     passing special attributes or objects.
     
-    :param cache_dir:
+    :param cache_dir: Filesystem directory where cache files will be
+     placed.  See :ref:`caching_toplevel`.
     
-    :param cache_enabled:
+    :param cache_enabled: Boolean flag which enables caching of this
+     template.  See :ref:`caching_toplevel`.
     
-    :param cache_type:
+    :param cache_type: Type of Beaker caching to be applied to the 
+     template. See :ref:`caching_toplevel`.
     
-    :param cache_url:
+    :param cache_url: URL of a memcached server with which to use
+     for caching.  See :ref:`caching_toplevel`.
 
-    :param default_filters:
+    :param default_filters: List of string filter names that will
+     be applied to all expressions.  See :ref:`filtering_default_filters`.
 
-    :param disable_unicode:
+    :param disable_unicode: Disables all awareness of Python Unicode
+     objects.  See :ref:`unicode_disabled`.
 
-    :param encoding_errors:
+    :param encoding_errors: Error parameter passed to ``encode()`` when
+     string encoding is performed. See :ref:`usage_unicode`.
     
-    :param error_handler:
+    :param error_handler: Python callable which is called whenever
+     compile or runtime exceptions occur.  The callable is passed the 
+     current context as well as the exception.  If the callable returns
+     ``True``, the exception is considered to be handled, else it
+     is re-raised after the function completes.  Is used to provide custom
+     error-rendering functions.
     
     :param format_exceptions: if ``True``, exceptions which occur during
      the render phase of this template will be caught and
@@ -56,22 +74,36 @@ class Template(object):
      rendered result of the :meth:`render` call. Otherwise,
      runtime exceptions are propagated outwards.
      
-    :param imports:
+    :param imports: String list of Python statements, typically individual
+     "import" lines, which will be placed into the module level preamble
+     of all generated Python modules.  See the example in :ref:`filtering_default_filters`.
 
-    :param input_encoding:
+    :param input_encoding: Encoding of the template's source code.  Can
+     be used in lieu of the coding comment.  
+     See :ref:`usage_unicode` as well as :ref:`unicode_toplevel`
+     for details on source encoding.
     
-    :param lookup:
+    :param lookup: a :class:`.TemplateLookup` instance that will be used
+     for all file lookups via the ``<%namespace>``, ``<%include>``, 
+     and ``<%inherit>`` tags.  See :ref:`usage_templatelookup`.
     
     :param module_directory: Filesystem location where generated Python
      module files will be placed.
 
-    :param module_filename:
+    :param module_filename: Overrides the filename of the generated Python
+     module file.  For advanced usage only. 
     
-    :param output_encoding:
+    :param output_encoding: The encoding to use when :meth:`.render` is called.
+      See :ref:`usage_unicode` as well as :ref:`unicode_toplevel`.
     
-    :param preprocessor:
-    
-    :param strict_undefined:
+    :param preprocessor: Python callable which will be passed the full template
+     source before it is parsed.  The return result of the callable will be used
+     as the template source code.
+     
+    :param strict_undefined: Replaces the automatic usage of ``UNDEFINED`` for
+     any undeclared variables not located in the :class:`.Context` with an immediate
+     raise of ``NameError``.  The advantage is immediate reporting of missing
+     variables which include the name.  New in 0.3.6.
     
     :param uri: string uri or other identifier for this template.  If not provided,
      the uri is generated from the filesystem path, or from the
@@ -80,7 +112,6 @@ class Template(object):
      generate the file path of the generated Python module file,
      if ``module_directory`` is specified.
     
-    
     """
     
     def __init__(self,