documentation update

 * added a number of internal links (L{...})
 * some fixes
 * some additions

5 files changed, 27 insertions, 18 deletions

diff --git a/wsgitools/authentication.py b/wsgitools/authentication.py
index 0c69f95..6f5d07b 100644
--- a/wsgitools/authentication.py
+++ b/wsgitools/authentication.py
@@ -82,7 +82,7 @@ class AuthenticationMiddleware:
         """Generates a WWW-Authenticate header. Subclasses must implement this
         method.
 
-        @type exception: AuthenticationRequired
+        @type exception: L{AuthenticationRequired}
         @param exception: reason for generating the header
         @rtype: (str, str)
         @returns: the header as (part_before_colon, part_after_colon)
@@ -93,7 +93,7 @@ class AuthenticationMiddleware:
         """Generate an error page after failed authentication. Apart from the
         exception parameter, this method behaves like a WSGI application.
 
-        @type exception: AuthenticationRequired
+        @type exception: L{AuthenticationRequired}
         @param exception: reason for the authentication failure
         """
         status = "401 Authorization required"
diff --git a/wsgitools/digest.py b/wsgitools/digest.py
index ded5e8d..6781e94 100644
--- a/wsgitools/digest.py
+++ b/wsgitools/digest.py
@@ -144,7 +144,7 @@ class AbstractTokenGenerator:
         @type username: str
         @type algo: str
         @param algo: currently the only value supported by
-                AuthDigestMiddleware is "md5"
+                L{AuthDigestMiddleware} is "md5"
         @rtype: str or None
         @returns: a valid token or None to signal that authentication should
                 fail
@@ -203,6 +203,7 @@ class HtdigestTokenGenerator(AbstractTokenGenerator):
         """
         @type realm: str
         @type htdigestfile: str
+        @param htdigestfile: path to the .htdigest file
         @type ignoreparseerrors: bool
         @param ignoreparseerrors: passed to readhtdigest
         @raises IOError:
@@ -241,11 +242,13 @@ class HtdigestTokenGenerator(AbstractTokenGenerator):
 
 __all__.append("UpdatingHtdigestTokenGenerator")
 class UpdatingHtdigestTokenGenerator(HtdigestTokenGenerator):
-    """Behaves like HtdigestTokenGenerator, checks the htdigest file
+    """Behaves like L{HtdigestTokenGenerator}, checks the htdigest file
     for changes on each invocation.
     """
     def __init__(self, realm, htdigestfile, ignoreparseerrors=False):
         assert isinstance(htdigestfile, str)
+        # Need to stat the file before calling parent ctor to detect
+        # modifications.
         try:
             self.statcache = os.stat(htdigestfile)
         except OSError, err:
@@ -256,6 +259,8 @@ class UpdatingHtdigestTokenGenerator(HtdigestTokenGenerator):
         self.ignoreparseerrors = ignoreparseerrors
 
     def __call__(self, user, algo="md5"):
+        # The interface does not permit raising exceptions, so all we can do is
+        # fail by returning None.
         try:
             statcache = os.stat(self.htdigestfile)
         except OSError:
@@ -358,8 +363,7 @@ class StatelessNonceStore(NonceStoreBase):
 
     def checknonce(self, nonce, count=1, ident=None):
         """
-        Do a check for whether the provided string is a nonce and increase usage
-        count on returning True.
+        Check whether the provided string is a nonce.
         @type nonce: str
         @type count: int
         @type ident: None or str
@@ -488,9 +492,9 @@ __all__.append("LazyDBAPI2Opener")
 class LazyDBAPI2Opener:
     """
     Connects to database on first request. Otherwise it behaves like a dbapi2
-    connection. This may be usefull in combination with scgi.forkpool, because
-    this way each worker child opens a new database connection when the first
-    request is to be answered.
+    connection. This may be usefull in combination with L{scgi.forkpool},
+    because this way each worker child opens a new database connection when
+    the first request is to be answered.
     """
     def __init__(self, function, *args, **kwargs):
         """
@@ -525,7 +529,8 @@ __all__.append("DBAPI2NonceStore")
 class DBAPI2NonceStore(NonceStoreBase):
     """
     A dbapi2-backed nonce store implementation suitable for usage with forking
-    wsgi servers such as scgi.forkpool.
+    wsgi servers such as L{scgi.forkpool}.
+
     >>> import sqlite3
     >>> db = sqlite3.connect(":memory:")
     >>> db.cursor().execute("CREATE TABLE nonces (key, value);") and None
@@ -676,9 +681,10 @@ class AuthDigestMiddleware(AuthenticationMiddleware):
                 L{AuthTokenGenerator} class.
         @type maxage: int
         @param maxage: deprecated, see L{MemoryNonceStore} or
-                L{StatelessNonceStore}
+                L{StatelessNonceStore} and pass an instance to store
         @type maxuses: int
-        @param maxuses: deprecated, see L{MemoryNonceStore}
+        @param maxuses: deprecated, see L{MemoryNonceStore} and pass an
+                instance to store
         @type store: L{NonceStoreBase}
         @param store: a nonce storage implementation object. Usage of this
                 parameter will override maxage and maxuses.
diff --git a/wsgitools/filters.py b/wsgitools/filters.py
index e455cbe..7ae1b69 100644
--- a/wsgitools/filters.py
+++ b/wsgitools/filters.py
@@ -383,8 +383,7 @@ class GzipWSGIFilter(BaseWSGIFilter):
     def __init__(self, flush=True):
         """
         @type flush: bool
-        @param flush: when true does not pump data necessarily immediately but
-                      accumulate to get a better compression ratio
+        @param flush: whether or not the filter should always flush the buffer
         """
         BaseWSGIFilter.__init__(self)
         self.flush = flush
diff --git a/wsgitools/scgi/asynchronous.py b/wsgitools/scgi/asynchronous.py
index e1dbcc6..6b69c73 100644
--- a/wsgitools/scgi/asynchronous.py
+++ b/wsgitools/scgi/asynchronous.py
@@ -218,8 +218,8 @@ class SCGIServer(asyncore.dispatcher):
         @type reusesocket: None or socket.socket
         @param reusesocket: If a socket is passed, do not create a socket.
                 Instead use given socket as listen socket. The passed socket
-                must be set up for accepting tcp connections (i.e. AF_INET,
-                SOCK_STREAM with bind and listen called).
+                must be set up for accepting tcp connections (i.e. C{AF_INET},
+                C{SOCK_STREAM} with bind and listen called).
         """
         if reusesocket is None:
             asyncore.dispatcher.__init__(self)
diff --git a/wsgitools/scgi/forkpool.py b/wsgitools/scgi/forkpool.py
index 8ccd579..39c9dfd 100644
--- a/wsgitools/scgi/forkpool.py
+++ b/wsgitools/scgi/forkpool.py
@@ -163,6 +163,10 @@ class SCGIServer:
         """state: 0 means idle and 1 means working.
         These values are also sent as strings '0' and '1' over the socket."""
         def __init__(self, pid, sock, state):
+            """
+            @type pid: int
+            @type state: int
+            """
             self.pid = pid
             self.sock = sock
             self.state = state
@@ -192,8 +196,8 @@ class SCGIServer:
         @type reusesocket: None or socket.socket
         @param reusesocket: If a socket is passed, do not create a socket.
                 Instead use given socket as listen socket. The passed socket
-                must be set up for accepting tcp connections (i.e. AF_INET,
-                SOCK_STREAM with bind and listen called).
+                must be set up for accepting tcp connections (i.e. C{AF_INET},
+                C{SOCK_STREAM} with bind and listen called).
         """
         assert hasattr(error, "write")
         self.wsgiapp = wsgiapp