Finalize interface for keyed hashes, and add a paragraph to the rationale

section describing the reasoning behind using (key, [string]) as the
    signature.

This PEP is ready to be marked Final.

pep-0247.txt

@@ -23,15 +23,16 @@ Specification
 
     Hash function modules define one function:
 
-    new([string])
-    new([key] , [string])
+    new([string])            (unkeyed hashes)
+    new([key] , [string])    (keyed hashes)
 
         Create a new hashing object and return it.  The first form is
-        for hashes that are unkeyed; most hashes such as MD5 or SHA
-        are unkeyed.  For keyed hashes such as HMAC, 'key' is a string
-        containing the starting key.  The 'string' parameter, if
-        supplied, will be immediately hashed into the object's
-        starting state, as if obj.update(string) was called.
+        for hashes that are unkeyed, such as MD5 or SHA.  For keyed
+        hashes such as HMAC, 'key' is a required parameter containing
+        a string giving the key to use.  In both cases, the optional
+        'string' parameter, if supplied, will be immediately hashed
+        into the object's starting state, as if obj.update(string) was
+        called.
         
         After creating a hashing object, arbitrary strings can be fed
         into the object using its update() method, and the hash value
@@ -132,6 +133,16 @@ Rationale
     used by the md5 and sha modules included with Python, so it seems
     simplest to leave the name update() alone.
 
+    The order of the constructor's arguments for keyed hashes was a
+    sticky issue.  It wasn't clear whether the key should come first
+    or second.  It's a required parameter, and the usual convention is
+    to place required parameters first, but that also means that the
+    'string' parameter moves from the first position to the second.
+    It would be possible to get confused and pass a single argument to
+    a keyed hash, thinking that you're passing an initial string to an 
+    unkeyed hash, but it doesn't seem worth making the interface 
+    for keyed hashes more obscure to avoid this potential error.
+
 
 Changes