diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index aa90010..0456e0d 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -792,12 +792,12 @@
  * \retval #PSA_SUCCESS
  * \retval #PSA_ERROR_INVALID_HANDLE
  * \retval #PSA_ERROR_OCCUPIED_SLOT
- *         \p target already contains key material.
+ *         \p target_handle already contains key material.
  * \retval #PSA_ERROR_EMPTY_SLOT
- *         \p source does not contain key material.
+ *         \p source_handle does not contain key material.
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  *         The policy constraints on the source, on the target and
- *         \p constraints are incompatible.
+ *         \p constraint are incompatible.
  * \retval #PSA_ERROR_NOT_PERMITTED
  *         The source key is not exportable and its lifetime does not
  *         allow copying it to the target's lifetime.
@@ -1152,7 +1152,7 @@
  * \retval #PSA_ERROR_EMPTY_SLOT
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
- *         \p key is not compatible with \p alg.
+ *         \p handle is not compatible with \p alg.
  * \retval #PSA_ERROR_NOT_SUPPORTED
  *         \p alg is not supported or is not a MAC algorithm.
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -1191,7 +1191,7 @@
  * \retval #PSA_ERROR_EMPTY_SLOT
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
- *         \p key is not compatible with \p alg.
+ *         \p handle is not compatible with \p alg.
  * \retval #PSA_ERROR_NOT_SUPPORTED
  *         \p alg is not supported or is not a MAC algorithm.
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -1294,7 +1294,7 @@
  * \retval #PSA_ERROR_EMPTY_SLOT
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
- *         \p key is not compatible with \p alg.
+ *         \p handle is not compatible with \p alg.
  * \retval #PSA_ERROR_NOT_SUPPORTED
  *         \p alg is not supported or is not a MAC algorithm.
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -1532,7 +1532,7 @@
  * \retval #PSA_ERROR_EMPTY_SLOT
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
- *         \p key is not compatible with \p alg.
+ *         \p handle is not compatible with \p alg.
  * \retval #PSA_ERROR_NOT_SUPPORTED
  *         \p alg is not supported or is not a cipher algorithm.
  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
@@ -1574,7 +1574,7 @@
  * \retval #PSA_ERROR_EMPTY_SLOT
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
- *         \p key is not compatible with \p alg.
+ *         \p handle is not compatible with \p alg.
  * \retval #PSA_ERROR_NOT_SUPPORTED
  *         \p alg is not supported or is not a cipher algorithm.
  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
@@ -1680,7 +1680,7 @@
  * \retval #PSA_ERROR_EMPTY_SLOT
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
- *         \p key is not compatible with \p alg.
+ *         \p handle is not compatible with \p alg.
  * \retval #PSA_ERROR_NOT_SUPPORTED
  *         \p alg is not supported or is not a cipher algorithm.
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -1739,7 +1739,7 @@
  * \retval #PSA_ERROR_EMPTY_SLOT
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
- *         \p key is not compatible with \p alg.
+ *         \p handle is not compatible with \p alg.
  * \retval #PSA_ERROR_NOT_SUPPORTED
  *         \p alg is not supported or is not a cipher algorithm.
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -1967,7 +1967,7 @@
  * \retval #PSA_ERROR_EMPTY_SLOT
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
- *         \p key is not compatible with \p alg.
+ *         \p handle is not compatible with \p alg.
  * \retval #PSA_ERROR_NOT_SUPPORTED
  *         \p alg is not supported or is not an AEAD algorithm.
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -2025,7 +2025,7 @@
  *         The ciphertext is not authentic.
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
- *         \p key is not compatible with \p alg.
+ *         \p handle is not compatible with \p alg.
  * \retval #PSA_ERROR_NOT_SUPPORTED
  *         \p alg is not supported or is not an AEAD algorithm.
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -2144,7 +2144,7 @@
  * \retval #PSA_ERROR_EMPTY_SLOT
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
- *         \p key is not compatible with \p alg.
+ *         \p handle is not compatible with \p alg.
  * \retval #PSA_ERROR_NOT_SUPPORTED
  *         \p alg is not supported or is not an AEAD algorithm.
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -2206,7 +2206,7 @@
  * \retval #PSA_ERROR_EMPTY_SLOT
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
- *         \p key is not compatible with \p alg.
+ *         \p handle is not compatible with \p alg.
  * \retval #PSA_ERROR_NOT_SUPPORTED
  *         \p alg is not supported or is not an AEAD algorithm.
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -2444,7 +2444,7 @@
  *   psa_aead_update() does not buffer any output and therefore \p ciphertext
  *   will not contain any output and can be a 0-sized buffer.
  * - \p tag contains the authentication tag. Its length is always
- *   #PSA_AEAD_TAG_LENGTH(\p alg) where \p alg is the AEAD algorithm
+ *   #PSA_AEAD_TAG_LENGTH(\c alg) where \c alg is the AEAD algorithm
  *   that the operation performs.
  *
  * When this function returns, the operation becomes inactive.
@@ -2467,7 +2467,7 @@
  *         The operation state is not valid (not set up, nonce not set,
  *         decryption, or already completed).
  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
- *         The size of the \p output buffer is too small.
+ *         The size of the \p ciphertext or \p tag buffer is too small.
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  *         The total length of input to psa_aead_update_ad() so far is
  *         less than the additional data length that was previously
@@ -2574,7 +2574,7 @@
  * \param handle                Handle to the key to use for the operation.
  *                              It must be an asymmetric key pair.
  * \param alg                   A signature algorithm that is compatible with
- *                              the type of \p key.
+ *                              the type of \p handle.
  * \param[in] hash              The hash or message to sign.
  * \param hash_length           Size of the \p hash buffer in bytes.
  * \param[out] signature        Buffer where the signature is to be written.
@@ -2588,7 +2588,7 @@
  *         determine a sufficient buffer size by calling
  *         #PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
  *         where \c key_type and \c key_bits are the type and bit-size
- *         respectively of \p key.
+ *         respectively of \p handle.
  * \retval #PSA_ERROR_NOT_SUPPORTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -2621,7 +2621,7 @@
  * \param handle            Handle to the key to use for the operation.
  *                          It must be a public key or an asymmetric key pair.
  * \param alg               A signature algorithm that is compatible with
- *                          the type of \p key.
+ *                          the type of \p handle.
  * \param[in] hash          The hash or message whose signature is to be
  *                          verified.
  * \param hash_length       Size of the \p hash buffer in bytes.
@@ -2658,7 +2658,7 @@
  *                              It must be a public key or an asymmetric
  *                              key pair.
  * \param alg                   An asymmetric encryption algorithm that is
- *                              compatible with the type of \p key.
+ *                              compatible with the type of \p handle.
  * \param[in] input             The message to encrypt.
  * \param input_length          Size of the \p input buffer in bytes.
  * \param[in] salt              A salt or label, if supported by the
@@ -2685,7 +2685,7 @@
  *         determine a sufficient buffer size by calling
  *         #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
  *         where \c key_type and \c key_bits are the type and bit-size
- *         respectively of \p key.
+ *         respectively of \p handle.
  * \retval #PSA_ERROR_NOT_SUPPORTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -2714,7 +2714,7 @@
  * \param handle                Handle to the key to use for the operation.
  *                              It must be an asymmetric key pair.
  * \param alg                   An asymmetric encryption algorithm that is
- *                              compatible with the type of \p key.
+ *                              compatible with the type of \p handle.
  * \param[in] input             The message to decrypt.
  * \param input_length          Size of the \p input buffer in bytes.
  * \param[in] salt              A salt or label, if supported by the
@@ -2741,7 +2741,7 @@
  *         determine a sufficient buffer size by calling
  *         #PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
  *         where \c key_type and \c key_bits are the type and bit-size
- *         respectively of \p key.
+ *         respectively of \p handle.
  * \retval #PSA_ERROR_NOT_SUPPORTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -2904,7 +2904,7 @@
  *         If the key is persistent, the key material and the key's metadata
  *         have been saved to persistent storage.
  * \retval #PSA_ERROR_INSUFFICIENT_CAPACITY
- *                          There were fewer than \p output_length bytes
+ *                          There were fewer than \p bits * 8 bytes
  *                          in the generator. Note that in this case, no
  *                          output is written to the output buffer.
  *                          The generator's capacity is set to 0, thus
@@ -3112,8 +3112,8 @@
  *                                psa_key_derivation_setup() with a
  *                                key agreement and derivation algorithm
  *                                \c alg (\c PSA_ALG_XXX value such that
- *                                #PSA_ALG_IS_KEY_AGREEMENT(\p alg) is true
- *                                and #PSA_ALG_IS_RAW_KEY_AGREEMENT(\p alg)
+ *                                #PSA_ALG_IS_KEY_AGREEMENT(\c alg) is true
+ *                                and #PSA_ALG_IS_RAW_KEY_AGREEMENT(\c alg)
  *                                is false).
  *                                The generator must be ready for an
  *                                input of the type given by \p step.
diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index a0eac4d..d14edd9 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -125,7 +125,7 @@
  * FIMXE This function is no longer part of the official API. Its prototype
  * is only kept around for the sake of tests that haven't been updated yet.
  *
- * A key derivation algorithm takes three inputs: a secret input \p key and
+ * A key derivation algorithm takes three inputs: a secret input \p handle and
  * two non-secret inputs \p label and p salt.
  * The result of this function is a byte generator which can
  * be used to produce keys and other cryptographic material.
diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h
index 0b40c5f..f6ce04e 100644
--- a/include/psa/crypto_values.h
+++ b/include/psa/crypto_values.h
@@ -691,7 +691,7 @@
  *
  * This value may not be used to build other algorithms that are
  * parametrized over a hash. For any valid use of this macro to build
- * an algorithm `\p alg`, #PSA_ALG_IS_HASH_AND_SIGN(\p alg) is true.
+ * an algorithm \c alg, #PSA_ALG_IS_HASH_AND_SIGN(\c alg) is true.
  *
  * This value may not be used to build an algorithm specification to
  * perform an operation. It is only valid to build policies.
@@ -708,7 +708,7 @@
  *                      #PSA_ALG_IS_HASH(\p hash_alg) is true).
  *
  * \return              The corresponding HMAC algorithm.
- * \return              Unspecified if \p alg is not a supported
+ * \return              Unspecified if \p hash_alg is not a supported
  *                      hash algorithm.
  */
 #define PSA_ALG_HMAC(hash_alg)                                  \
@@ -954,7 +954,7 @@
  *                      when specifying the algorithm in a usage policy.
  *
  * \return              The corresponding RSA PKCS#1 v1.5 signature algorithm.
- * \return              Unspecified if \p alg is not a supported
+ * \return              Unspecified if \p hash_alg is not a supported
  *                      hash algorithm.
  */
 #define PSA_ALG_RSA_PKCS1V15_SIGN(hash_alg)                             \
@@ -985,7 +985,7 @@
  *                      when specifying the algorithm in a usage policy.
  *
  * \return              The corresponding RSA PSS signature algorithm.
- * \return              Unspecified if \p alg is not a supported
+ * \return              Unspecified if \p hash_alg is not a supported
  *                      hash algorithm.
  */
 #define PSA_ALG_RSA_PSS(hash_alg)                               \
@@ -1005,7 +1005,7 @@
  *                      when specifying the algorithm in a usage policy.
  *
  * \return              The corresponding DSA signature algorithm.
- * \return              Unspecified if \p alg is not a supported
+ * \return              Unspecified if \p hash_alg is not a supported
  *                      hash algorithm.
  */
 #define PSA_ALG_DSA(hash_alg)                             \
@@ -1023,7 +1023,7 @@
  *                      when specifying the algorithm in a usage policy.
  *
  * \return              The corresponding DSA signature algorithm.
- * \return              Unspecified if \p alg is not a supported
+ * \return              Unspecified if \p hash_alg is not a supported
  *                      hash algorithm.
  */
 #define PSA_ALG_DETERMINISTIC_DSA(hash_alg)                             \
@@ -1056,7 +1056,7 @@
  *                      when specifying the algorithm in a usage policy.
  *
  * \return              The corresponding ECDSA signature algorithm.
- * \return              Unspecified if \p alg is not a supported
+ * \return              Unspecified if \p hash_alg is not a supported
  *                      hash algorithm.
  */
 #define PSA_ALG_ECDSA(hash_alg)                                 \
@@ -1091,7 +1091,7 @@
  *
  * \return              The corresponding deterministic ECDSA signature
  *                      algorithm.
- * \return              Unspecified if \p alg is not a supported
+ * \return              Unspecified if \p hash_alg is not a supported
  *                      hash algorithm.
  */
 #define PSA_ALG_DETERMINISTIC_ECDSA(hash_alg)                           \
@@ -1163,7 +1163,7 @@
  *                      for MGF1.
  *
  * \return              The corresponding RSA OAEP signature algorithm.
- * \return              Unspecified if \p alg is not a supported
+ * \return              Unspecified if \p hash_alg is not a supported
  *                      hash algorithm.
  */
 #define PSA_ALG_RSA_OAEP(hash_alg)                              \
@@ -1193,7 +1193,7 @@
  *                      #PSA_ALG_IS_HASH(\p hash_alg) is true).
  *
  * \return              The corresponding HKDF algorithm.
- * \return              Unspecified if \p alg is not a supported
+ * \return              Unspecified if \p hash_alg is not a supported
  *                      hash algorithm.
  */
 #define PSA_ALG_HKDF(hash_alg)                                  \
@@ -1234,7 +1234,7 @@
  *                      #PSA_ALG_IS_HASH(\p hash_alg) is true).
  *
  * \return              The corresponding TLS-1.2 PRF algorithm.
- * \return              Unspecified if \p alg is not a supported
+ * \return              Unspecified if \p hash_alg is not a supported
  *                      hash algorithm.
  */
 #define PSA_ALG_TLS12_PRF(hash_alg)                                  \
@@ -1274,7 +1274,7 @@
  *                      #PSA_ALG_IS_HASH(\p hash_alg) is true).
  *
  * \return              The corresponding TLS-1.2 PSK to MS algorithm.
- * \return              Unspecified if \p alg is not a supported
+ * \return              Unspecified if \p hash_alg is not a supported
  *                      hash algorithm.
  */
 #define PSA_ALG_TLS12_PSK_TO_MS(hash_alg)                                  \