1 files changed, 33 insertions, 4 deletions
diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst
index 20fa23cf..312d7e69 100644
--- a/docs/hazmat/primitives/cryptographic-hashes.rst
+++ b/docs/hazmat/primitives/cryptographic-hashes.rst
@@ -5,7 +5,7 @@ Message Digests
 
 .. currentmodule:: cryptography.hazmat.primitives.hashes
 
-.. class:: Hash(algorithm)
+.. class:: Hash(algorithm, backend)
 
     A cryptographic hash function takes an arbitrary block of data and
     calculates a fixed-size bit string (a digest), such that different data
@@ -20,30 +20,56 @@ Message Digests
 
     .. doctest::
 
+        >>> from cryptography.hazmat.bindings import default_backend
         >>> from cryptography.hazmat.primitives import hashes
-        >>> digest = hashes.Hash(hashes.SHA256())
+        >>> digest = hashes.Hash(hashes.SHA256(), backend=default_backend())
         >>> digest.update(b"abc")
         >>> digest.update(b"123")
         >>> digest.finalize()
         'l\xa1=R\xcap\xc8\x83\xe0\xf0\xbb\x10\x1eBZ\x89\xe8bM\xe5\x1d\xb2\xd29%\x93\xafj\x84\x11\x80\x90'
 
+    Keep in mind that attacks against cryptographic hashes only get stronger
+    with time, and that often algorithms that were once thought to be strong,
+    become broken. Because of this it's important to include a plan for
+    upgrading the hash algorithm you use over time. For more information, see
+    `Lifetimes of cryptographic hash functions`_.
+
+    :param algorithm: A
+        :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`
+        provider such as those described in
+        :ref:`below <cryptographic-hash-algorithms>`.
+    :param backend: A
+        :class:`~cryptography.hazmat.bindings.interfaces.HashBackend`
+        provider.
+
     .. method:: update(data)
 
         :param bytes data: The bytes you wish to hash.
+        :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`
 
     .. method:: copy()
 
-        :return: a new instance of this object with a copied internal state.
+        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.
+
+        :return: A new instance of :class:`Hash` which can be updated
+            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.
+        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`.
 
         :return bytes: The message digest as bytes.
 
 
+.. _cryptographic-hash-algorithms:
+
 SHA-1
 ~~~~~
 
@@ -109,3 +135,6 @@ MD5
 
     MD5 is a deprecated cryptographic hash function. It has a 128-bit message
     digest and has practical known collision attacks.
+
+
+.. _`Lifetimes of cryptographic hash functions`: http://valerieaurora.org/hash.html