Update HMAC and Digest docs.

1 files changed, 14 insertions, 13 deletions

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: