Added comments for algorithms module and register_algorithm.

2 files changed, 31 insertions, 0 deletions

diff --git a/jwt/__init__.py b/jwt/__init__.py
index a1c11e2..b9a9986 100644
--- a/jwt/__init__.py
+++ b/jwt/__init__.py
@@ -40,6 +40,7 @@ _algorithms = {}
 
 
 def register_algorithm(alg_id, alg_obj):
+    """ Registers a new Algorithm for use when creating and verifying JWTs """
     if alg_id in _algorithms:
         raise ValueError('Algorithm already has a handler.')
 
diff --git a/jwt/algorithms.py b/jwt/algorithms.py
index 9390636..3e8ea38 100644
--- a/jwt/algorithms.py
+++ b/jwt/algorithms.py
@@ -19,6 +19,7 @@ except ImportError:
 
 
 def _register_default_algorithms():
+    """ Registers the algorithms that are implemented by the library """
     register_algorithm('none', NoneAlgorithm())
     register_algorithm('HS256', HMACAlgorithm(hashlib.sha256))
     register_algorithm('HS384', HMACAlgorithm(hashlib.sha384))
@@ -35,17 +36,33 @@ def _register_default_algorithms():
 
 
 class Algorithm(object):
+    """ The interface for an algorithm used to sign and verify JWTs """
     def prepare_key(self, key):
+        """
+        Performs necessary validation and conversions on the key and returns
+        the key value in the proper format for sign() and verify()
+        """
         raise NotImplementedError
 
     def sign(self, msg, key):
+        """
+        Returns a digital signature for the specified message using the
+        specified key value
+        """
         raise NotImplementedError
 
     def verify(self, msg, key, sig):
+        """
+        Verifies that the specified digital signature is valid for the specified
+        message and key values.
+        """
         raise NotImplementedError
 
 
 class NoneAlgorithm(Algorithm):
+    """
+    Placeholder for use when no signing or verification operations are required
+    """
     def prepare_key(self, key):
         return None
 
@@ -57,6 +74,10 @@ class NoneAlgorithm(Algorithm):
 
 
 class HMACAlgorithm(Algorithm):
+    """
+    Performs signing and verification operations using HMAC and the specified
+    hash function
+    """
     def __init__(self, hash_alg):
         self.hash_alg = hash_alg
 
@@ -78,6 +99,11 @@ class HMACAlgorithm(Algorithm):
 if has_crypto:
 
     class RSAAlgorithm(Algorithm):
+        """
+        Performs signing and verification operations using RSASSA-PKCS-v1_5 and
+        the specified hash function
+        """
+
         def __init__(self, hash_alg):
             self.hash_alg = hash_alg
 
@@ -127,6 +153,10 @@ if has_crypto:
                 return False
 
     class ECAlgorithm(Algorithm):
+        """
+        Performs signing and verification operations using ECDSA and the
+        specified hash function
+        """
         def __init__(self, hash_alg):
             self.hash_alg = hash_alg