Update HMAC and Digest docs.

2 files changed, 38 insertions, 37 deletions

diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst
index 86b85852..627ca7bd 100644
--- a/docs/hazmat/primitives/cryptographic-hashes.rst
+++ b/docs/hazmat/primitives/cryptographic-hashes.rst
@@ -29,7 +29,7 @@ Message Digests
         'l\xa1=R\xcap\xc8\x83\xe0\xf0\xbb\x10\x1eBZ\x89\xe8bM\xe5\x1d\xb2\xd29%\x93\xafj\x84\x11\x80\x90'
 
     If the backend doesn't support the requested ``algorithm`` an
-    :class:`~cryptography.exceptions.UnsupportedHash` will be raised.
+    :class:`~cryptography.exceptions.UnsupportedHash` exception will be raised.
 
     Keep in mind that attacks against cryptographic hashes only get stronger
     with time, and that often algorithms that were once thought to be strong,
@@ -47,26 +47,26 @@ Message Digests
 
     .. method:: update(data)
 
-        :param bytes data: The bytes you wish to hash.
-        :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`
+        :param bytes data: The bytes to be hashed.
+        :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`.
 
     .. method:: copy()
 
-        Copy this :class:`Hash` instance, usually so that we may call
-        :meth:`finalize` and get an intermediate digest value while we continue
-        to call :meth:`update` on the original.
+        Copy this :class:`Hash` instance, usually so that you may call
+        :meth:`finalize` to get an intermediate digest value while we continue
+        to call :meth:`update` on the original instance.
 
         :return: A new instance of :class:`Hash` that can be updated
-            and finalized independently of the original instance.
-        :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`
+             and finalized independently of the original instance.
+        :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`.
 
     .. method:: finalize()
 
         Finalize the current context and return the message digest as bytes.
 
-        Once ``finalize`` is called this object can no longer be used and
-        :meth:`update`, :meth:`copy`, and :meth:`finalize` will raise
-        :class:`~cryptography.exceptions.AlreadyFinalized`.
+        After ``finalize`` has been called this object can no longer be used
+        and :meth:`update`, :meth:`copy`, and :meth:`finalize` will raise an
+        :class:`~cryptography.exceptions.AlreadyFinalized` exception.
 
         :return bytes: The message digest as bytes.
 
@@ -83,7 +83,7 @@ SHA-1
 
 .. class:: SHA1()
 
-    SHA-1 is a cryptographic hash function standardized by NIST. It has a
+    SHA-1 is a cryptographic hash function standardized by NIST. It produces an
     160-bit message digest.
 
 SHA-2 Family
@@ -91,23 +91,23 @@ SHA-2 Family
 
 .. class:: SHA224()
 
-    SHA-224 is a cryptographic hash function from the SHA-2 family and
-    standardized by NIST. It has a 224-bit message digest.
+    SHA-224 is a cryptographic hash function from the SHA-2 family and is
+    standardized by NIST. It produces a 224-bit message digest.
 
 .. class:: SHA256()
 
-    SHA-256 is a cryptographic hash function from the SHA-2 family and
-    standardized by NIST. It has a 256-bit message digest.
+    SHA-256 is a cryptographic hash function from the SHA-2 family and is
+    standardized by NIST. It produces a 256-bit message digest.
 
 .. class:: SHA384()
 
-    SHA-384 is a cryptographic hash function from the SHA-2 family and
-    standardized by NIST. It has a 384-bit message digest.
+    SHA-384 is a cryptographic hash function from the SHA-2 family and is
+    standardized by NIST. It produces a 384-bit message digest.
 
 .. class:: SHA512()
 
-    SHA-512 is a cryptographic hash function from the SHA-2 family and
-    standardized by NIST. It has a 512-bit message digest.
+    SHA-512 is a cryptographic hash function from the SHA-2 family and is
+    standardized by NIST. It produces a 512-bit message digest.
 
 RIPEMD160
 ~~~~~~~~~
@@ -115,7 +115,7 @@ RIPEMD160
 .. class:: RIPEMD160()
 
     RIPEMD160 is a cryptographic hash function that is part of ISO/IEC
-    10118-3:2004. It has a 160-bit message digest.
+    10118-3:2004. It produces a 160-bit message digest.
 
 Whirlpool
 ~~~~~~~~~
@@ -123,7 +123,7 @@ Whirlpool
 .. class:: Whirlpool()
 
     Whirlpool is a cryptographic hash function that is part of ISO/IEC
-    10118-3:2004. It has a 512-bit message digest.
+    10118-3:2004. It produces a 512-bit message digest.
 
 MD5
 ~~~
@@ -136,8 +136,8 @@ MD5
 
 .. class:: MD5()
 
-    MD5 is a deprecated cryptographic hash function. It has a 128-bit message
-    digest and has practical known collision attacks.
+    MD5 is a deprecated cryptographic hash function. It produces a 128-bit
+    message digest and has practical known collision attacks.
 
 
 .. _`Lifetimes of cryptographic hash functions`: http://valerieaurora.org/hash.html
diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst
index 1a2838f7..6ca9e167 100644
--- a/docs/hazmat/primitives/hmac.rst
+++ b/docs/hazmat/primitives/hmac.rst
@@ -12,13 +12,13 @@ Hash-based Message Authentication Codes
 
 Hash-based message authentication codes (or HMACs) are a tool for calculating
 message authentication codes using a cryptographic hash function coupled with a
-secret key. You can use an HMAC to verify integrity as well as authenticate a
-message.
+secret key. You can use an HMAC to verify both the integrity and authenticity
+of a message.
 
 .. class:: HMAC(key, algorithm, backend)
 
-    HMAC objects take a ``key`` and a provider of
-    :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`.
+    HMAC objects take a ``key`` and a
+    :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` provider.
     The ``key`` should be randomly generated bytes and is recommended to be
     equal in length to the ``digest_size`` of the hash function chosen.
     You must keep the ``key`` secret.
@@ -35,7 +35,7 @@ message.
         '#F\xdaI\x8b"e\xc4\xf1\xbb\x9a\x8fc\xff\xf5\xdex.\xbc\xcd/+\x8a\x86\x1d\x84\'\xc3\xa6\x1d\xd8J'
 
     If the backend doesn't support the requested ``algorithm`` an
-    :class:`~cryptography.exceptions.UnsupportedHash` will be raised.
+    :class:`~cryptography.exceptions.UnsupportedHash` exception will be raised.
 
     To check that a given signature is correct use the :meth:`verify` method.
     You will receive an exception if the signature is wrong:
@@ -47,12 +47,12 @@ message.
         ...
         cryptography.exceptions.InvalidSignature: Signature did not match digest.
 
-    :param key: Secret key as ``bytes``.
-    :param algorithm: A
+    :param bytes key: Secret key as ``bytes``.
+    :param algorithm: An
         :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`
         provider such as those described in
         :ref:`Cryptographic Hashes <cryptographic-hash-algorithms>`.
-    :param backend: A
+    :param backend: An
         :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`
         provider.
 
@@ -64,8 +64,8 @@ message.
     .. method:: copy()
 
         Copy this :class:`HMAC` instance, usually so that we may call
-        :meth:`finalize` and get an intermediate digest value while we continue
-        to call :meth:`update` on the original.
+        :meth:`finalize` to get an intermediate digest value while we continue
+        to call :meth:`update` on the original instance.
 
         :return: A new instance of :class:`HMAC` that can be updated
             and finalized independently of the original instance.
@@ -86,9 +86,10 @@ message.
 
         Finalize the current context and return the message digest as bytes.
 
-        Once ``finalize`` is called this object can no longer be used and
-        :meth:`update`, :meth:`copy`, and :meth:`finalize` will raise
-        :class:`~cryptography.exceptions.AlreadyFinalized`.
+        After ``finalize`` has been called this object can no longer be used
+        and :meth:`update`, :meth:`copy`, :meth:`verify` and :meth:`finalize`
+        will raise an :class:`~cryptography.exceptions.AlreadyFinalized`
+        exception.
 
         :return bytes: The message digest as bytes.
         :raises cryptography.exceptions.AlreadyFinalized: