more docstring/epydoc improvements

1 files changed, 20 insertions, 4 deletions

diff --git a/wsgitools/digest.py b/wsgitools/digest.py
index 695272c..b4f9f36 100755
--- a/wsgitools/digest.py
+++ b/wsgitools/digest.py
@@ -14,6 +14,13 @@ import time
 sysrand = random.SystemRandom()
 
 def gen_rand_str(bytes=33):
+    """
+    Generates a string of random base64 characters.
+    @param bytes: is the number of random 8bit values to be used
+
+    >>> gen_rand_str() != gen_rand_str()
+    True
+    """
     randnum = sysrand.getrandbits(bytes*8)
     randstr = ("%%0%dX" % (2*bytes)) % randnum
     randstr = binascii.unhexlify(randstr)
@@ -56,7 +63,10 @@ def parse_digest_response(data, ret=dict()):
     return parse_digest_response(rest, ret)
 
 class AuthenticationRequired(Exception):
-    pass
+    """
+    Internal Exception class that is thrown inside L{AuthDigestMiddleware}, but
+    not visible to other code.
+    """
 
 __all__.append("AuthTokenGenerator")
 class AuthTokenGenerator:
@@ -76,7 +86,7 @@ class AuthTokenGenerator:
     def __call__(self, username, algo="md5"):
         """Generates an authentification token from a username.
         @type username: str
-        @rtype: str
+        @rtype: str or None
         """
         assert algo.lower() in ["md5", "md5-sess"]
         password = self.getpass(username)
@@ -161,6 +171,7 @@ class StatelessNonceStore(NonceStoreBase):
     def newnonce(self, ident=None):
         """
         Generates a new nonce string.
+        @type ident: None or str
         @rtype: str
         """
         nonce_time = format_time(time.time())
@@ -177,6 +188,7 @@ class StatelessNonceStore(NonceStoreBase):
         count on returning True.
         @type nonce: str
         @type count: int
+        @type ident: None or str
         @rtype: bool
         """
         if count != 1:
@@ -237,6 +249,7 @@ class MemoryNonceStore(NonceStoreBase):
     def newnonce(self, ident=None):
         """
         Generates a new nonce string.
+        @type ident: None or str
         @rtype: str
         """
         self._cleanup() # avoid growing self.nonces
@@ -255,6 +268,7 @@ class MemoryNonceStore(NonceStoreBase):
         count on returning True.
         @type nonce: str
         @type count: int
+        @type ident: None or str
         @rtype: bool
         """
         try:
@@ -297,7 +311,9 @@ __all__.append("LazyDBAPI2Opener")
 class LazyDBAPI2Opener:
     """
     Connects to database on first request. Otherwise it behaves like a dbapi2
-    connection.
+    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.
     """
     def __init__(self, function, *args, **kwargs):
         """
@@ -445,7 +461,7 @@ class AuthDigestMiddleware:
     def __init__(self, app, gentoken, maxage=300, maxuses=5, store=None):
         """
         @param app: is the wsgi application to be served with authentification.
-        @type gentoken: str -> str
+        @type gentoken: str -> (str or None)
         @param gentoken: has to have the same functionality and interface as the
                 L{AuthTokenGenerator} class.
         @type maxage: int