diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 0ec67d7..bf7fd18 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -1593,7 +1593,8 @@
 /** Encrypt a message using a symmetric cipher.
  *
  * This function encrypts a message with a random IV (initialization
- * vector).
+ * vector). Use the multipart #psa_cipher_operation_t object to provide
+ * other foms of IV.
  *
  * \param handle                Handle to the key to use for the operation.
  *                              It must remain valid until the operation
@@ -1737,7 +1738,7 @@
  *    listed here.
  * -# Initialize the operation object with one of the methods described in the
  *    documentation for #psa_cipher_operation_t, e.g.
- *    PSA_CIPHER_OPERATION_INIT.
+ *    #PSA_CIPHER_OPERATION_INIT.
  * -# Call psa_cipher_encrypt_setup() to specify the algorithm and key.
  * -# Call either psa_cipher_generate_iv() or psa_cipher_set_iv() to
  *    generate or set the IV (initialization vector). You should use
@@ -1747,14 +1748,16 @@
  *    of the message each time.
  * -# Call psa_cipher_finish().
  *
- * The application may call psa_cipher_abort() at any time after the operation
+ * If an error occurs at any step after a call to psa_cipher_encrypt_setup(),
+ * the operation will need to be reset by a call to psa_cipher_abort(). The
+ * application may call psa_cipher_abort() at any time after the operation
  * has been initialized.
  *
  * After a successful call to psa_cipher_encrypt_setup(), the application must
  * eventually terminate the operation. The following events terminate an
  * operation:
- * - A failed call to any of the \c psa_cipher_xxx functions.
- * - A call to psa_cipher_finish() or psa_cipher_abort().
+ * - A successful call to psa_cipher_finish().
+ * - A call to psa_cipher_abort().
  *
  * \param[in,out] operation     The operation object to set up. It must have
  *                              been initialized as per the documentation for
@@ -1780,8 +1783,7 @@
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
- *         The operation state is not valid (already set up and not
- *         subsequently completed).
+ *         The operation state is not valid (it must be inactive).
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
@@ -1799,7 +1801,7 @@
  *    listed here.
  * -# Initialize the operation object with one of the methods described in the
  *    documentation for #psa_cipher_operation_t, e.g.
- *    PSA_CIPHER_OPERATION_INIT.
+ *    #PSA_CIPHER_OPERATION_INIT.
  * -# Call psa_cipher_decrypt_setup() to specify the algorithm and key.
  * -# Call psa_cipher_set_iv() with the IV (initialization vector) for the
  *    decryption. If the IV is prepended to the ciphertext, you can call
@@ -1809,14 +1811,16 @@
  *    of the message each time.
  * -# Call psa_cipher_finish().
  *
- * The application may call psa_cipher_abort() at any time after the operation
+ * If an error occurs at any step after a call to psa_cipher_decrypt_setup(),
+ * the operation will need to be reset by a call to psa_cipher_abort(). The
+ * application may call psa_cipher_abort() at any time after the operation
  * has been initialized.
  *
  * After a successful call to psa_cipher_decrypt_setup(), the application must
  * eventually terminate the operation. The following events terminate an
  * operation:
- * - A failed call to any of the \c psa_cipher_xxx functions.
- * - A call to psa_cipher_finish() or psa_cipher_abort().
+ * - A successful call to psa_cipher_finish().
+ * - A call to psa_cipher_abort().
  *
  * \param[in,out] operation     The operation object to set up. It must have
  *                              been initialized as per the documentation for
@@ -1842,8 +1846,7 @@
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
- *         The operation state is not valid (already set up and not
- *         subsequently completed).
+ *         The operation state is not valid (it must be inactive).
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
@@ -1862,7 +1865,8 @@
  * The application must call psa_cipher_encrypt_setup() before
  * calling this function.
  *
- * If this function returns an error status, the operation becomes inactive.
+ * If this function returns an error status, the operation enters an error
+ * state and must be aborted by calling psa_cipher_abort().
  *
  * \param[in,out] operation     Active cipher operation.
  * \param[out] iv               Buffer where the generated IV is to be written.
@@ -1873,7 +1877,7 @@
  * \retval #PSA_SUCCESS
  *         Success.
  * \retval #PSA_ERROR_BAD_STATE
- *         The operation state is not valid (not set up, or IV already set).
+ *         The operation state is not valid (it must be active, with no IV set).
  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
  *         The size of the \p iv buffer is too small.
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -1899,7 +1903,8 @@
  * The application must call psa_cipher_encrypt_setup() before
  * calling this function.
  *
- * If this function returns an error status, the operation becomes inactive.
+ * If this function returns an error status, the operation enters an error
+ * state and must be aborted by calling psa_cipher_abort().
  *
  * \note When encrypting, applications should use psa_cipher_generate_iv()
  * instead of this function, unless implementing a protocol that requires
@@ -1912,7 +1917,8 @@
  * \retval #PSA_SUCCESS
  *         Success.
  * \retval #PSA_ERROR_BAD_STATE
- *         The operation state is not valid (not set up, or IV already set).
+ *         The operation state is not valid (it must be an active cipher
+ *         encrypt operation, with no IV set).
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  *         The size of \p iv is not acceptable for the chosen algorithm,
  *         or the chosen algorithm does not use an IV.
@@ -1939,7 +1945,8 @@
  * 2. If the algorithm requires an IV, call psa_cipher_generate_iv()
  *    (recommended when encrypting) or psa_cipher_set_iv().
  *
- * If this function returns an error status, the operation becomes inactive.
+ * If this function returns an error status, the operation enters an error
+ * state and must be aborted by calling psa_cipher_abort().
  *
  * \param[in,out] operation     Active cipher operation.
  * \param[in] input             Buffer containing the message fragment to
@@ -1953,8 +1960,8 @@
  * \retval #PSA_SUCCESS
  *         Success.
  * \retval #PSA_ERROR_BAD_STATE
- *         The operation state is not valid (not set up, IV required but
- *         not set, or already completed).
+ *         The operation state is not valid (it must be active, with an IV set
+ *         if required for the algorithm).
  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
  *         The size of the \p output buffer is too small.
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -1985,7 +1992,9 @@
  * formed by concatenating the inputs passed to preceding calls to
  * psa_cipher_update().
  *
- * When this function returns, the operation becomes inactive.
+ * When this function returns successfuly, the operation becomes inactive.
+ * If this function returns an error status, the operation enters an error
+ * state and must be aborted by calling psa_cipher_abort().
  *
  * \param[in,out] operation     Active cipher operation.
  * \param[out] output           Buffer where the output is to be written.
@@ -2004,8 +2013,8 @@
  *         This is a decryption operation for an algorithm that includes
  *         padding, and the ciphertext does not contain valid padding.
  * \retval #PSA_ERROR_BAD_STATE
- *         The operation state is not valid (not set up, IV required but
- *         not set, or already completed).
+ *         The operation state is not valid (it must be active, with an IV set
+ *         if required for the algorithm).
  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
  *         The size of the \p output buffer is too small.
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -2031,12 +2040,7 @@
  * psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup() again.
  *
  * You may call this function any time after the operation object has
- * been initialized by any of the following methods:
- * - A call to psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup(),
- *   whether it succeeds or not.
- * - Initializing the \c struct to all-bits-zero.
- * - Initializing the \c struct to logical zeros, e.g.
- *   `psa_cipher_operation_t operation = {0}`.
+ * been initialized as described in #psa_cipher_operation_t.
  *
  * In particular, calling psa_cipher_abort() after the operation has been
  * terminated by a call to psa_cipher_abort() or psa_cipher_finish()
@@ -2045,8 +2049,6 @@
  * \param[in,out] operation     Initialized cipher operation.
  *
  * \retval #PSA_SUCCESS
- * \retval #PSA_ERROR_BAD_STATE
- *         \p operation is not an active cipher operation.
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED