improved digest documentation

1 files changed, 16 insertions, 3 deletions

diff --git a/wsgitools/digest.py b/wsgitools/digest.py
index 42abaa9..bb587fa 100755
--- a/wsgitools/digest.py
+++ b/wsgitools/digest.py
@@ -1,4 +1,16 @@
 #!/usr/bin/env python2.5
+"""
+This module contains an C{AuthDigestMiddleware} for authenticating HTTP
+requests using the method described in RFC2617. The credentials are to be
+provided using an C{AuthTokenGenerator} or a compatible instance. Furthermore
+digest authentication has to preserve some state across requests, more
+specifically nonces. There are three different C{NonceStoreBase}
+implementations for different needs. While the C{StatelessNonceStore} has
+minimal requirements it only prevents replay attacks in a limited way. If the
+WSGI server uses threading or a single process the C{MemoryNonceStore} can be
+used. If that is not possible the nonces can be stored in a DBAPI2 compatible
+database using C{DBAPI2NonceStore}.
+"""
 
 __all__ = []
 
@@ -84,9 +96,10 @@ class AuthTokenGenerator:
         """
         @type realm: str
         @param realm: is a string according to RFC2617.
-        @type getpass: str -> str
+        @type getpass: str -> (str or None)
         @param getpass: this function is called with a username and password is
                 expected as result. C{None} may be used as an invalid password.
+                An example for getpass would be C{{username: password}.get}.
         """
         self.realm = realm
         self.getpass = getpass
@@ -572,8 +585,8 @@ class AuthDigestMiddleware:
 
     def auth_response(self, credentials, reqmethod):
         """internal method generating authentication tokens
-        @raise KeyError:
-        @raise ValueError:
+        @raises KeyError:
+        @raises ValueError:
         """
         username = credentials["username"]
         algo = credentials["algorithm"]