1 files changed, 27 insertions, 9 deletions
diff --git a/docs/primitives/symmetric-encryption.rst b/docs/primitives/symmetric-encryption.rst
index 96bd68f0..73d8ad37 100644
--- a/docs/primitives/symmetric-encryption.rst
+++ b/docs/primitives/symmetric-encryption.rst
@@ -15,29 +15,47 @@ where the encrypter and decrypter both use the same key.
 
     Block ciphers work by encrypting content in chunks, often 64- or 128-bits.
     They combine an underlying algorithm (such as AES), with a mode (such as
-    CBC, CTR, or GCM). A simple example of encrypting content with AES is:
+    CBC, CTR, or GCM). A simple example of encrypting (and then decrypting)
+    content with AES is:
 
     .. doctest::
 
         >>> from cryptography.primitives.block import BlockCipher, ciphers, modes
         >>> cipher = BlockCipher(ciphers.AES(key), modes.CBC(iv))
-        >>> cipher.encrypt(b"a secret message") + cipher.finalize()
-        '...'
+        >>> encryptor = cipher.encryptor()
+        >>> ct = encryptor.update(b"a secret message") + encryptor.finalize()
+        >>> decryptor = cipher.decryptor()
+        >>> decryptor.update(ct) + decryptor.finalize()
+        'a secret message'
 
     :param cipher: One of the ciphers described below.
     :param mode: One of the modes described below.
 
-    ``encrypt()`` should be called repeatedly with new plaintext, and once the
-    full plaintext is fed in, ``finalize()`` should be called.
+    .. method:: encryptor()
 
-    .. method:: encrypt(plaintext)
+        :return :class:`CipherContext`: encryption instance
 
-        :param bytes plaintext: The text you wish to encrypt.
-        :return bytes: Returns the ciphertext that was added.
+    .. method:: decryptor()
+
+        :return :class:`CipherContext`: decryption instance
+
+.. class:: cryptography.primitives.interfaces.CipherContext()
+
+    When calling ``encryptor()`` or ``decryptor()`` on a BlockCipher object you
+    will receive a return object conforming to the CipherContext interface. You
+    can then call ``update(data)`` with data until you have fed everything into
+    the context. Once that is done call ``finalize()`` to finish the operation and
+    obtain the remainder of the data.
+
+
+    .. method:: update(data)
+
+        :param bytes data: The text you wish to pass into the context.
+        :return bytes: Returns the data that was encrypted or decrypted.
 
     .. method:: finalize()
 
-        :return bytes: Returns the remainder of the ciphertext.
+        :return bytes: Returns the remainder of the data.
 
 Ciphers
 ~~~~~~~