diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 90140d7..060c007 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -18,7 +18,7 @@
 /** \brief Key slot number.
  *
  * This type represents key slots. It must be an unsigned integral
- * type.* The choice of type is implementation-dependent.
+ * type. The choice of type is implementation-dependent.
  * 0 is not a valid key slot number. The meaning of other values is
  * implementation dependent.
  *
@@ -98,12 +98,12 @@
  * Applications may call this function more than once. Once a call
  * succeeds, subsequent calls are guaranteed to succeed.
  *
- * \return * \c PSA_SUCCESS: success.
- *         * \c PSA_ERROR_INSUFFICIENT_MEMORY
- *         * \c PSA_ERROR_COMMUNICATION_FAILURE
- *         * \c PSA_ERROR_HARDWARE_FAILURE
- *         * \c PSA_ERROR_TAMPERING_DETECTED
- *         * \c PSA_ERROR_INSUFFICIENT_ENTROPY
+ * \retval PSA_SUCCESS
+ * \retval PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval PSA_ERROR_HARDWARE_FAILURE
+ * \retval PSA_ERROR_TAMPERING_DETECTED
+ * \retval PSA_ERROR_INSUFFICIENT_ENTROPY
  */
 psa_status_t psa_crypto_init(void);
 
@@ -116,6 +116,8 @@
  * @{
  */
 
+/** \brief Encoding of a key type.
+ */
 typedef uint32_t psa_key_type_t;
 
 #define PSA_KEY_TYPE_NONE                       ((psa_key_type_t)0x00000000)
@@ -133,7 +135,9 @@
 #define PSA_KEY_TYPE_CAMELLIA                   ((psa_key_type_t)0x04000003)
 #define PSA_KEY_TYPE_ARC4                       ((psa_key_type_t)0x04000004)
 
+/** RSA public key. */
 #define PSA_KEY_TYPE_RSA_PUBLIC_KEY             ((psa_key_type_t)0x06010000)
+/** RSA key pair (private and public key). */
 #define PSA_KEY_TYPE_RSA_KEYPAIR                ((psa_key_type_t)0x07010000)
 #define PSA_KEY_TYPE_ECC_BASE                   ((psa_key_type_t)0x06030000)
 #define PSA_KEY_TYPE_ECC_CURVE_MASK             ((psa_key_type_t)0x0000ffff)
@@ -153,6 +157,14 @@
 #define PSA_KEY_TYPE_IS_ECC(type)                                       \
     (((type) & ~PSA_KEY_TYPE_ECC_CURVE_MASK) == PSA_KEY_TYPE_ECC_BASE)
 
+/** \brief Encoding of a cryptographic algorithm.
+ *
+ * For algorithms that can be applied to multiple key types, this type
+ * does not encode the key type. For example, for symmetric ciphers
+ * based on a block cipher, #psa_algorithm_t encodes the block cipher
+ * mode and the padding mode while the block cipher itself is encoded
+ * via #psa_key_type_t.
+ */
 typedef uint32_t psa_algorithm_t;
 
 #define PSA_ALG_VENDOR_FLAG                     ((psa_algorithm_t)0x80000000)
@@ -168,6 +180,13 @@
 
 #define PSA_ALG_IS_VENDOR_DEFINED(alg)                                  \
     (((alg) & PSA_ALG_VENDOR_FLAG) != 0)
+/** Whether the specified algorithm is a hash algorithm.
+ *
+ * \param alg An algorithm identifier (\c PSA_ALG_XXX value)
+ *
+ * \return 1 if \c alg is a hash algorithm, 0 otherwise.
+ *         This macro may return either 0 or 1 if \c alg is not a valid
+ *         algorithm identifier. */
 #define PSA_ALG_IS_HASH(alg)                                            \
     (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_HASH)
 #define PSA_ALG_IS_MAC(alg)                                             \
@@ -245,13 +264,26 @@
  *
  * This function supports any output from psa_export_key().
  *
- * \return * \c PSA_SUCCESS: success.
- *         * \c PSA_ERROR_NOT_SUPPORTED
- *         * \c PSA_ERROR_INVALID_ARGUMENT
- *         * \c PSA_ERROR_INSUFFICIENT_MEMORY
- *         * \c PSA_ERROR_COMMUNICATION_FAILURE
- *         * \c PSA_ERROR_HARDWARE_FAILURE
- *         * \c PSA_ERROR_TAMPERING_DETECTED
+ * \param key         Slot where the key will be stored. This must be a
+ *                    valid slot for a key of the chosen type. It must
+ *                    be unoccupied.
+ * \param type        Key type (a \c PSA_KEY_TYPE_XXX value).
+ * \param data        Buffer containing the key data.
+ * \param data_length Size of the \c data buffer in bytes.
+ *
+ * \retval PSA_SUCCESS
+ *         Success.
+ * \retval PSA_ERROR_NOT_SUPPORTED
+ *         The key type or key size is not supported.
+ * \retval PSA_ERROR_INVALID_ARGUMENT
+ *         The key slot is invalid,
+ *         or the key data is not correctly formatted.
+ * \retval PSA_ERROR_OCCUPIED_SLOT
+           There is already a key in the specified slot.
+ * \retval PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval PSA_ERROR_HARDWARE_FAILURE
+ * \retval PSA_ERROR_TAMPERING_DETECTED
  */
 psa_status_t psa_import_key(psa_key_slot_t key,
                             psa_key_type_t type,
@@ -261,22 +293,31 @@
 /**
  * \brief Destroy a key.
  *
- * \return * \c PSA_SUCCESS: success.
- *         * \c PSA_ERROR_EMPTY_SLOT
- *         * \c PSA_ERROR_COMMUNICATION_FAILURE
- *         * \c PSA_ERROR_HARDWARE_FAILURE
- *         * \c PSA_ERROR_TAMPERING_DETECTED
+ * \retval PSA_SUCCESS
+ * \retval PSA_ERROR_EMPTY_SLOT
+ * \retval PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval PSA_ERROR_HARDWARE_FAILURE
+ * \retval PSA_ERROR_TAMPERING_DETECTED
  */
 psa_status_t psa_destroy_key(psa_key_slot_t key);
 
 /**
  * \brief Get basic metadata about a key.
  *
- * \return * \c PSA_SUCCESS: success.
- *         * \c PSA_ERROR_EMPTY_SLOT
- *         * \c PSA_ERROR_COMMUNICATION_FAILURE
- *         * \c PSA_ERROR_HARDWARE_FAILURE
- *         * \c PSA_ERROR_TAMPERING_DETECTED
+ * \param key           Slot whose content is queried. This must
+ *                      be an occupied key slot.
+ * \param type          On success, the key type (a \c PSA_KEY_TYPE_XXX value).
+ *                      This may be a null pointer, in which case the key type
+ *                      is not written.
+ * \param bits          On success, the key size in bits.
+ *                      This may be a null pointer, in which case the key type
+ *                      is not written.
+ *
+ * \retval PSA_SUCCESS
+ * \retval PSA_ERROR_EMPTY_SLOT
+ * \retval PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval PSA_ERROR_HARDWARE_FAILURE
+ * \retval PSA_ERROR_TAMPERING_DETECTED
  */
 psa_status_t psa_get_key_information(psa_key_slot_t key,
                                      psa_key_type_t *type,
@@ -293,11 +334,32 @@
  * identical: the implementation may choose a different representation
  * of the same key.
  *
- * \return * \c PSA_SUCCESS: success.
- *         * \c PSA_ERROR_EMPTY_SLOT
- *         * \c PSA_ERROR_COMMUNICATION_FAILURE
- *         * \c PSA_ERROR_HARDWARE_FAILURE
- *         * \c PSA_ERROR_TAMPERING_DETECTED
+ * For standard key types, the output format is as follows:
+ *
+ * - For symmetric keys (including MAC keys), the format is the
+ *   raw bytes of the key.
+ * - For DES, the key data consists of 8 bytes. The parity bits must be
+ *   correct.
+ * - For Triple-DES, the format is the concatenation of the
+ *   two or three DES keys.
+ * - For RSA key pairs keys (#PSA_KEY_TYPE_RSA_KEYPAIR), the format
+ *   is the non-encrypted DER representation defined by PKCS\#8 (RFC 5208)
+ *   as PrivateKeyInfo.
+ * - For RSA public keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY), the format
+ *   is the DER representation defined by X.509.
+ *
+ * \param key           Slot whose content is to be exported. This must
+ *                      be an occupied key slot.
+ * \param data          Buffer where the key data is to be written.
+ * \param data_size     Size of the \c data buffer in bytes.
+ * \param data_length   On success, the number of bytes
+ *                      that make up the key data.
+ *
+ * \retval PSA_SUCCESS
+ * \retval PSA_ERROR_EMPTY_SLOT
+ * \retval PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval PSA_ERROR_HARDWARE_FAILURE
+ * \retval PSA_ERROR_TAMPERING_DETECTED
  */
 psa_status_t psa_export_key(psa_key_slot_t key,
                             uint8_t *data,
@@ -311,8 +373,25 @@
  * @{
  */
 
+/** The type of the state data structure for multipart hash operations.
+ *
+ * This is an implementation-define \c struct. Applications should not
+ * make any assumptions about the content of this structure except
+ * as directed by the documentation of a specific implementation. */
 typedef struct psa_hash_operation_s psa_hash_operation_t;
 
+/** The size of the output of psa_hash_finish(), in bytes.
+ *
+ * This is also the hash size that psa_hash_verify() expects.
+ *
+ * \param alg   A hash algorithm (\c PSA_ALG_XXX value such that
+ *              #PSA_ALG_IS_HASH(alg) is true).
+ *
+ * \return The hash size for the specified hash algorithm.
+ *         If the hash algorithm is not recognized, return 0.
+ *         An implementation may return either 0 or the correct size
+ *         for a hash algorithm that it recognizes, but does not support.
+ */
 #define PSA_HASH_FINAL_SIZE(alg)                \
     (                                           \
         (alg) == PSA_ALG_MD2 ? 16 :             \
@@ -334,27 +413,168 @@
         (alg) == PSA_ALG_SHA3_512 ? 64 :        \
         0)
 
+/** Start a multipart hash operation.
+ *
+ * The sequence of operations to calculate a hash (message digest)
+ * is as follows:
+ * -# Allocate an operation object which will be passed to all the functions
+ *    listed here.
+ * -# Call psa_hash_start() to specify the algorithm.
+ * -# Call psa_hash_update() zero, one or more time, passing a fragment
+ *    of the message each time. The hash that is calculated is the hash
+ *    of the concatenation of these messages in order.
+ * -# To calculate the hash, call psa_hash_finish().
+ *    To compare the hash with an expected value, call psa_hash_verify().
+ *
+ * The application may call psa_hash_abort() at any time after the operation
+ * has been initialized with psa_hash_start().
+ *
+ * After a successful call to psa_hash_start(), the application must
+ * eventually destroy the operation through one of the following means:
+ * - A failed call to psa_hash_update().
+ * - A call to psa_hash_final(), psa_hash_verify() or psa_hash_abort().
+ *
+ * \param operation
+ * \param alg       The hash algorithm to compute (\c PSA_ALG_XXX value
+ *                  such that #PSA_ALG_IS_HASH(alg) is true).
+ *
+ * \retval PSA_SUCCESS
+ *         Success.
+ * \retval PSA_ERROR_NOT_SUPPORTED
+ *         \c alg is not supported or is not a hash algorithm.
+ * \retval PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval PSA_ERROR_HARDWARE_FAILURE
+ * \retval PSA_ERROR_TAMPERING_DETECTED
+ */
 psa_status_t psa_hash_start(psa_hash_operation_t *operation,
                             psa_algorithm_t alg);
 
+/** Add a message fragment to a multipart hash operation.
+ *
+ * The application must call psa_hash_start() before calling this function.
+ *
+ * If this function returns an error status, the operation becomes inactive.
+ *
+ * \param operation     Active hash operation.
+ * \param input         Buffer containing the message fragment to hash.
+ * \param input_length  Size of the \c input buffer in bytes.
+ *
+ * \retval PSA_SUCCESS
+ *         Success.
+ * \retval PSA_ERROR_BAD_STATE
+ *         The operation state is not valid (not started, or already completed).
+ * \retval PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval PSA_ERROR_HARDWARE_FAILURE
+ * \retval PSA_ERROR_TAMPERING_DETECTED
+ */
 psa_status_t psa_hash_update(psa_hash_operation_t *operation,
                              const uint8_t *input,
                              size_t input_length);
 
+/** Finish the calculation of the hash of a message.
+ *
+ * The application must call psa_hash_start() before calling this function.
+ * This function calculates the hash of the message formed by concatenating
+ * the inputs passed to preceding calls to psa_hash_update().
+ *
+ * When this function returns, the operation becomes inactive.
+ *
+ * \warning Applications should not call this function if they expect
+ *          a specific value for the hash. Call psa_hash_verify() instead.
+ *          Beware that comparing integrity or authenticity data such as
+ *          hash values with a function such as \c memcmp is risky
+ *          because the time taken by the comparison may leak information
+ *          about the hashed data which could allow an attacker to guess
+ *          a valid hash and thereby bypass security controls.
+ *
+ * \param operation     Active hash operation.
+ * \param hash          Buffer where the hash is to be written.
+ * \param hash_size     Size of the \c hash buffer in bytes.
+ * \param hash_length   On success, the number of bytes
+ *                      that make up the hash value. This is always
+ *                      #PSA_HASH_FINAL_SIZE(alg) where \c alg is the
+ *                      hash algorithm that is calculated.
+ *
+ * \retval PSA_SUCCESS
+ *         Success.
+ * \retval PSA_ERROR_BAD_STATE
+ *         The operation state is not valid (not started, or already completed).
+ * \retval PSA_ERROR_BUFFER_TOO_SMALL
+ *         The size of the \c hash buffer is too small. You can determine a
+ *         sufficient buffer size by calling #PSA_HASH_FINAL_SIZE(alg)
+ *         where \c alg is the hash algorithm that is calculated.
+ * \retval PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval PSA_ERROR_HARDWARE_FAILURE
+ * \retval PSA_ERROR_TAMPERING_DETECTED
+ */
 psa_status_t psa_hash_finish(psa_hash_operation_t *operation,
                              uint8_t *hash,
                              size_t hash_size,
                              size_t *hash_length);
 
+/** Finish the calculation of the hash of a message and compare it with
+ * an expected value.
+ *
+ * The application must call psa_hash_start() before calling this function.
+ * This function calculates the hash of the message formed by concatenating
+ * the inputs passed to preceding calls to psa_hash_update(). It then
+ * compares the calculated hash with the expected hash passed as a
+ * parameter to this function.
+ *
+ * When this function returns, the operation becomes inactive.
+ *
+ * \note Applications shall make the best effort to ensure that the
+ * comparison between the actual hash and the expected hash is performed
+ * in constant time.
+ *
+ * \param operation     Active hash operation.
+ * \param hash          Buffer containing the expected hash value.
+ * \param hash_length   Size of the \c hash buffer in bytes.
+ *
+ * \retval PSA_SUCCESS
+ *         The expected hash is identical to the actual hash of the message.
+ * \retval PSA_ERROR_INVALID_SIGNATURE
+ *         The hash of the message was calculated successfully, but it
+ *         differs from the expected hash.
+ * \retval PSA_ERROR_BAD_STATE
+ *         The operation state is not valid (not started, or already completed).
+ * \retval PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval PSA_ERROR_HARDWARE_FAILURE
+ * \retval PSA_ERROR_TAMPERING_DETECTED
+ */
 psa_status_t psa_hash_verify(psa_hash_operation_t *operation,
                              const uint8_t *hash,
                              size_t hash_length);
 
-psa_status_t ps_hash_abort(psa_hash_operation_t *operation);
+/** Abort a hash operation.
+ *
+ * This function may be called at any time after psa_hash_start().
+ * Aborting an operation frees all associated resources except for the
+ * \c operation structure itself.
+ *
+ * Implementation should strive to be robust and handle inactive hash
+ * operations safely (do nothing and return #PSA_ERROR_BAD_STATE). However,
+ * application writers should beware that uninitialized memory may happen
+ * to be indistinguishable from an active hash operation, and the behavior
+ * of psa_hash_abort() is undefined in this case.
+ *
+ * \param operation     Active hash operation.
+ *
+ * \retval PSA_SUCCESS
+ * \retval PSA_ERROR_BAD_STATE
+ *         \c operation is not an active hash operation.
+ * \retval PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval PSA_ERROR_HARDWARE_FAILURE
+ * \retval PSA_ERROR_TAMPERING_DETECTED
+ */
+psa_status_t psa_hash_abort(psa_hash_operation_t *operation);
 
 /**@}*/
 
-/** \defgroup MAC Message authentication codes
 /** \defgroup asymmetric Asymmetric cryptography
  * @{
  */
@@ -389,6 +609,33 @@
       /*V of r,s*/               ((curve_bits) + 8) / 8))
 
 
+/** Safe signature buffer size for psa_asymmetric_sign().
+ *
+ * This macro returns a safe buffer size for a signature using a key
+ * of the specified type and size, with the specified algorithm.
+ * Note that the actual size of the signature may be smaller
+ * (some algorithms produce a variable-size signature).
+ *
+ * \warning This function may call its arguments multiple times or
+ *          zero times, so you should not pass arguments that contain
+ *          side effects.
+ *
+ * \param key_type  An asymmetric key type (this may indifferently be a
+ *                  key pair type or a public key type).
+ * \param key_bits  The size of the key in bits.
+ * \param alg       The signature algorithm.
+ *
+ * \return If the parameters are valid and supported, return
+ *         a buffer size in bytes that guarantees that
+ *         psa_asymmetric_sign() will not fail with
+ *         #PSA_ERROR_BUFFER_TOO_SMALL.
+ *         If the parameters are a valid combination that is not supported
+ *         by the implementation, this macro either shall return either a
+ *         sensible size or 0.
+ *         If the parameters are not valid, the
+ *         return value is unspecified.
+ *
+ */
 #define PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(key_type, key_bits, alg)        \
     (PSA_KEY_TYPE_IS_RSA(key_type) ? ((void)alg, BITS_TO_BYTES(key_bits)) : \
      PSA_KEY_TYPE_IS_ECC(key_type) ? PSA_ECDSA_SIGNATURE_SIZE(key_bits) : \
@@ -397,6 +644,41 @@
 /**
  * \brief Sign a hash or short message with a private key.
  *
+ * \param key               Key slot containing an asymmetric key pair.
+ * \param alg               A signature algorithm that is compatible with
+ *                          the type of \c key.
+ * \param hash              The message to sign.
+ * \param hash_length       Size of the \c hash buffer in bytes.
+ * \param salt              A salt or label, if supported by the signature
+ *                          algorithm.
+ *                          If the signature algorithm does not support a
+ *                          salt, pass \c NULL.
+ *                          If the signature algorithm supports an optional
+ *                          salt and you do not want to pass a salt,
+ *                          pass \c NULL.
+ * \param salt_length       Size of the \c salt buffer in bytes.
+ *                          If \c salt is \c NULL, pass 0.
+ * \param signature         Buffer where the signature is to be written.
+ * \param signature_size    Size of the \c signature buffer in bytes.
+ * \param signature_length  On success, the number of bytes
+ *                          that make up the returned signature value.
+ *                          This is at most #PSA_HASH_FINAL_SIZE(alg)
+ *                          (note that it may be less).
+ *
+ * \retval PSA_SUCCESS
+ * \retval PSA_ERROR_BUFFER_TOO_SMALL
+ *         The size of the \c signature buffer is too small. You can
+ *         determine a sufficient buffer size by calling
+ *         #PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(key_type, key_bits, alg)
+ *         where \c key_type and \c key_bits are the type and bit-size
+ *         respectively of \c key.
+ * \retval PSA_ERROR_NOT_SUPPORTED
+ * \retval PSA_ERROR_INVALID_ARGUMENT
+ * \retval PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval PSA_ERROR_HARDWARE_FAILURE
+ * \retval PSA_ERROR_TAMPERING_DETECTED
+ * \retval PSA_ERROR_INSUFFICIENT_ENTROPY
  */
 psa_status_t psa_asymmetric_sign(psa_key_slot_t key,
                                  psa_algorithm_t alg,
@@ -411,6 +693,35 @@
 /**
  * \brief Verify the signature a hash or short message using a public key.
  *
+ * \param key               Key slot containing a public key or an
+ *                          asymmetric key pair.
+ * \param alg               A signature algorithm that is compatible with
+ *                          the type of \c key.
+ * \param hash              The message whose signature is to be verified.
+ * \param hash_length       Size of the \c hash buffer in bytes.
+ * \param salt              A salt or label, if supported by the signature
+ *                          algorithm.
+ *                          If the signature algorithm does not support a
+ *                          salt, pass \c NULL.
+ *                          If the signature algorithm supports an optional
+ *                          salt and you do not want to pass a salt,
+ *                          pass \c NULL.
+ * \param salt_length       Size of the \c salt buffer in bytes.
+ *                          If \c salt is \c NULL, pass 0.
+ * \param signature         Buffer containing the signature to verify.
+ * \param signature_size    Size of the \c signature buffer in bytes.
+ *
+ * \retval PSA_SUCCESS
+ *         The signature is valid.
+ * \retval PSA_ERROR_INVALID_SIGNATURE
+ *         The calculation was perfomed successfully, but the passed
+ *         signature is not a valid signature.
+ * \retval PSA_ERROR_NOT_SUPPORTED
+ * \retval PSA_ERROR_INVALID_ARGUMENT
+ * \retval PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval PSA_ERROR_HARDWARE_FAILURE
+ * \retval PSA_ERROR_TAMPERING_DETECTED
  */
 psa_status_t psa_asymmetric_verify(psa_key_slot_t key,
                                    psa_algorithm_t alg,