Fix doc strings

5 files changed, 72 insertions, 22 deletions

diff --git a/paste/cgitb_catcher.py b/paste/cgitb_catcher.py
index 8e4d9d0..246adba 100644
--- a/paste/cgitb_catcher.py
+++ b/paste/cgitb_catcher.py
@@ -4,9 +4,9 @@
 """
 WSGI middleware
 
-Captures any exceptions and prints a pretty report.  See the cgitb
-documentation for more:
-  http://python.org/doc/current/lib/module-cgitb.html
+Captures any exceptions and prints a pretty report.  See the `cgitb
+documentation <http://python.org/doc/current/lib/module-cgitb.html>`_
+for more.
 """
 
 import cgitb
diff --git a/paste/exceptions/collector.py b/paste/exceptions/collector.py
index cd56544..8a92a9c 100644
--- a/paste/exceptions/collector.py
+++ b/paste/exceptions/collector.py
@@ -85,7 +85,7 @@ class ExceptionCollector:
     The actually interpretation of these values is largely up to the
     reporters and formatters.
     
-    collect_exception(*sys.exc_info()) will return an object with
+    ``collect_exception(*sys.exc_info())`` will return an object with
     several attributes:
 
     ``frames``:
@@ -464,11 +464,13 @@ col = ExceptionCollector()
 
 def collect_exception(t, v, tb, limit=None):
     """
-    Use like:
+    Collection an exception from ``sys.exc_info()``.
+    
+    Use like::
 
-    try:
-        blah blah
-    except:
-        exc_data = collect_exception(*sys.exc_info())
+      try:
+          blah blah
+      except:
+          exc_data = collect_exception(*sys.exc_info())
     """
     return col.collectException(t, v, tb, limit=limit)
diff --git a/paste/exceptions/errormiddleware.py b/paste/exceptions/errormiddleware.py
index a9cadf1..86d5d81 100644
--- a/paste/exceptions/errormiddleware.py
+++ b/paste/exceptions/errormiddleware.py
@@ -17,12 +17,16 @@ from paste.deploy import converters
 
 __all__ = ['ErrorMiddleware', 'handle_exception']
 
-class NoDefault:
-    pass
+class _NoDefault:
+    def __repr__(self):
+        return '<NoDefault>'
+NoDefault = _NoDefault()
 
 class ErrorMiddleware(object):
 
     """
+    Error handling middleware
+    
     Usage::
 
         error_caching_wsgi_app = ErrorMiddleware(wsgi_app)
@@ -31,9 +35,31 @@ class ErrorMiddleware(object):
     true value, this middleware is disabled.  This can be useful in a
     testing environment where you don't want errors to be caught and
     transformed.
+
+    Settings:
+
+    ``debug``:
+        If true, then tracebacks will be shown in the browser.
+
+    ``error_email``:
+        An email address (or list of addresses) to send exception reports
+        to.
+
+    ``error_log``:
+        A filename to append tracebacks to.
+
+    ``show_exceptions_in_wsgi_errors``:
+        If true, then errors will be printed to ``wsgi.errors`` (frequently
+        a server error log, or stderr).
+
+    ``from_address``, ``smtp_server``, ``error_subject_prefix``:
+        Variables to control the emailed exception reports.
+
+    ``error_message``:
+        When debug mode is off, the error message to show to users.
     """
 
-    def __init__(self, application, global_conf,
+    def __init__(self, application, global_conf=None,
                  debug=NoDefault,
                  error_email=None,
                  error_log=None,
@@ -43,6 +69,8 @@ class ErrorMiddleware(object):
                  error_subject_prefix=None,
                  error_message=None):
         self.application = application
+        if global_conf is None:
+            global_conf = {}
         if debug is NoDefault:
             debug = global_conf.get('debug')
         self.debug_mode = converters.asbool(debug)
@@ -66,6 +94,9 @@ class ErrorMiddleware(object):
         self.error_message = error_message
             
     def __call__(self, environ, start_response):
+        """
+        The WSGI application interface.
+        """
         # We want to be careful about not sending headers twice,
         # and the content type that the app has committed to (if there
         # is an exception in the iterator body of the response)
@@ -133,10 +164,17 @@ class ErrorMiddleware(object):
             error_message=self.error_message)
 
 class Supplement(object):
+
+    """
+    This is a supplement used to display standard WSGI information in
+    the traceback.
+    """
+
     def __init__(self, middleware, environ):
         self.middleware = middleware
         self.environ = environ
         self.source_url = wsgilib.construct_url(environ)
+
     def extraData(self):
         data = {}
         cgi_vars = data[('extra', 'CGI Variables')] = {}
@@ -186,8 +224,9 @@ def handle_exception(exc_info, error_stream, html=True,
                      error_message=None,
                      ):
     """
-    You can also use exception handling outside of a web context,
-    like::
+    For exception handling outside of a web context
+
+    Use like::
 
         import sys
         import paste
diff --git a/paste/fixture.py b/paste/fixture.py
index 034b266..7d4230f 100644
--- a/paste/fixture.py
+++ b/paste/fixture.py
@@ -447,7 +447,9 @@ class TestResponse(object):
     def mustcontain(self, *strings):
         """
         Assert that the response contains all of the strings passed
-        in as arguments.  Equivalent to::
+        in as arguments.
+
+        Equivalent to::
 
             assert string in res
         """
@@ -823,7 +825,10 @@ def _space_prefix(pref, full, sep=None, indent=None, include_sep=True):
 
 def setup_module(module=None):
     """
-    This is used by py.test if it is in the module, so do::
+    This is used by py.test if it is in the module, so you can
+    import this directly.
+
+    Use like::
 
         from paste.tests.fixture import setup_module
     """
diff --git a/paste/wsgilib.py b/paste/wsgilib.py
index 22c768e..b0dc35e 100644
--- a/paste/wsgilib.py
+++ b/paste/wsgilib.py
@@ -253,8 +253,9 @@ def error_body_response(error_code, message):
 def error_response(environ, error_code, message,
                    debug_message=None):
     """
-    Returns the status, headers, and body of an error response.  Use
-    like::
+    Returns the status, headers, and body of an error response.
+
+    Use like::
 
         status, headers, body = wsgilib.error_response(
             '301 Moved Permanently', 'Moved to <a href="%s">%s</a>'
@@ -372,7 +373,9 @@ def path_info_split(path_info):
 def path_info_pop(environ):
     """
     'Pops' off the next segment of PATH_INFO, pushing it onto
-    SCRIPT_NAME, and returning that segment.  For instance::
+    SCRIPT_NAME, and returning that segment.
+
+    For instance::
 
         >>> def call_it(script_name, path_info):
         ...     env = {'SCRIPT_NAME': script_name, 'PATH_INFO': path_info}
@@ -409,9 +412,10 @@ def path_info_pop(environ):
 def capture_output(environ, start_response, application):
     """
     Runs application with environ and start_response, and captures
-    status, headers, and body.  Sends status and header, but *not*
-    body.  Returns (status, headers, body).  Typically this is used
-    like::
+    status, headers, and body.
+
+    Sends status and header, but *not* body.  Returns (status,
+    headers, body).  Typically this is used like::
 
         def dehtmlifying_middleware(application):
             def replacement_app(environ, start_response):