diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 6706ef8..fa41022 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -4092,7 +4092,7 @@
 /**@}*/
 
 
-/** \defgroup Password-authenticated key agreement
+/** \defgroup pake Password-authenticated key exchange (PAKE)
  * @{
  */
 
@@ -4255,7 +4255,7 @@
  * -# Initialize the operation object with one of the methods described in the
  *    documentation for #psa_pake_operation_t, e.g.
  *    #PSA_PAKE_OPERATION_INIT.
- * -# Call psa_pake_setup() to specify cipher suite.
+ * -# Call psa_pake_setup() to specify the cipher suite.
  * -# Call \c psa_pake_set_xxx() functions on the operation to complete the
  *    setup. The exact sequence of \c psa_pake_set_xxx() functions that needs
  *    to be called depends on the algorithm in use.
@@ -4324,6 +4324,11 @@
 
 /** Set the password for a password-authenticated key exchange from key ID.
  *
+ * Call this function when the password, or a value derived from the password,
+ * is already present in the key store. To calculate the password-derived value
+ * from a password input, use the key derivation interface and
+ * psa_pake_set_password_stretch() instead.
+ *
  * \param[in,out] operation     The operation object to set the password for. It
  *                              must have been set up by psa_pake_setup() and
  *                              not yet in use.
@@ -4332,8 +4337,8 @@
  *                              memory-hard function).  It must remain valid
  *                              until the operation terminates. It must be of
  *                              type #PSA_KEY_TYPE_PASSWORD or
- *                              #PSA_KEY_TYPE_DERIVE. It has to allow the usage
- *                              #PSA_KEY_USAGE_DERIVE.
+ *                              #PSA_KEY_TYPE_PASSWORD_HASH. It has to allow
+ *                              the usage #PSA_KEY_USAGE_DERIVE.
  *
  * \retval #PSA_SUCCESS
  *         Success.
@@ -4409,7 +4414,7 @@
 
 /** Set the user ID for a password-authenticated key exchange.
  *
- * Some PAKE algorithms assiciate only a single user identifier with the
+ * Some PAKE algorithms associate only a single user identifier with the
  * session.  Such algorithms must call this function (psa_pake_set_user()) to
  * set the identifier for the PAKE context.
  *
@@ -4444,7 +4449,7 @@
 
 /** Set the peer ID for a password-authenticated key exchange.
  *
- * Some PAKE algorithms assiciate only a single user identifier with the
+ * Some PAKE algorithms associate only a single user identifier with the
  * session.  Such algorithms must call psa_pake_set_user() to set the
  * identifier for the PAKE context.
  *
@@ -4514,7 +4519,7 @@
 psa_status_t psa_pake_set_side(psa_pake_operation_t *operation,
                                psa_pake_side_t side);
 
-/** Get additional key share from a password-authenticated key exchange.
+/** Get output for a step of a password-authenticated key exchange.
  *
  * Depending on the algorithm being executed, you might need to call this
  * function several times or you might not need to call this at all.
@@ -4529,7 +4534,8 @@
  * state and must be aborted by calling psa_pake_abort().
  *
  * \param[in,out] operation    Active PAKE operation.
- * \param type                 The type of the data that is requested.
+ * \param step                 The step of the algorithm for which the output is
+ *                             requested.
  * \param[out] output          Buffer where the output is to be written.
  * \param output_size          Size of the \p output buffer in bytes. This must
  *                             be at least #PSA_PAKE_OUTPUT_SIZE(\p alg, \c
@@ -4556,12 +4562,12 @@
  *         results in this error code.
  */
 psa_status_t psa_pake_output(psa_pake_operation_t *operation,
-                             psa_pake_step_t type,
+                             psa_pake_step_t step,
                              uint8_t *output,
                              size_t output_size,
                              size_t *output_length);
 
-/** Provide additional peer key share for a password-authenticated key exchange.
+/** Provide input for a step of a password-authenticated key exchange.
  *
  * Depending on the algorithm being executed, you might need to call this
  * function several times or you might not need to call this at all.
@@ -4576,7 +4582,7 @@
  * state and must be aborted by calling psa_pake_abort().
  *
  * \param[in,out] operation    Active PAKE operation.
- * \param type                 The type of the data provided.
+ * \param step                 The step for which the input is provided.
  * \param[out] input           Buffer containing the input.
  * \param[out] input_length    Size of the \p input buffer in bytes.
  *
@@ -4596,7 +4602,7 @@
  *         results in this error code.
  */
 psa_status_t psa_pake_input(psa_pake_operation_t *operation,
-                             psa_pake_step_t type,
+                             psa_pake_step_t step,
                              uint8_t *input,
                              size_t input_length);
 
diff --git a/include/psa/crypto_sizes.h b/include/psa/crypto_sizes.h
index d8fc997..a603c9d 100644
--- a/include/psa/crypto_sizes.h
+++ b/include/psa/crypto_sizes.h
@@ -1143,7 +1143,8 @@
  *
  * \param alg           A PAKE algorithm (PSA_ALG_XXX value such that
  *                      #PSA_ALG_IS_PAKE(\p alg) is true).
- * \param primitive     A primitive that is compatible with algorithm \p alg.
+ * \param primitive     A primitive of type ::psa_pake_primitive_t that is
+ *                      compatible with algorithm \p alg.
  * \param output_step   A value of type ::psa_pake_step_t that is valid for the
  *                      algorithm \p alg.
  * \return              A sufficient output buffer size for the specified
diff --git a/include/psa/crypto_types.h b/include/psa/crypto_types.h
index 5418bd7..5a66a87 100644
--- a/include/psa/crypto_types.h
+++ b/include/psa/crypto_types.h
@@ -387,7 +387,7 @@
 /** \brief Encoding of the side of PAKE
  *
  * Encodes which side of the algorithm is being executed. For more information
- * see the documentation of individual PSA_PAKE_SIDE_XXX constants.
+ * see the documentation of individual \c PSA_PAKE_SIDE_XXX constants.
  */
 typedef uint8_t psa_pake_side_t;
 
@@ -405,14 +405,14 @@
  * Vendors who define additional types must use an encoding in this range.
  *
  * For more information see the documentation of individual
- * PSA_PAKE_PRIMITIVE_TYPE_XXX constants.
+ * \c PSA_PAKE_PRIMITIVE_TYPE_XXX constants.
  */
 typedef uint8_t psa_pake_primitive_type_t;
 
 /** \brief Encoding of the family of the primitive associated with the PAKE.
  *
  * For more information see the documentation of individual
- * PSA_PAKE_PRIMITIVE_TYPE_XXX constants.
+ * \c PSA_PAKE_PRIMITIVE_TYPE_XXX constants.
  */
 typedef uint8_t psa_pake_family_t;
 
diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h
index d1924db..c8a074c 100644
--- a/include/psa/crypto_values.h
+++ b/include/psa/crypto_values.h
@@ -1975,7 +1975,7 @@
  * cipher suite the field or curve must be fully specified by calling
  * psa_pake_cs_set_family() and psa_pake_cs_set_bits() as well. For more
  * information refer to the documentation of the individual
- * `PSA_PAKE_PRIMITIVE_TYPE_XXX` constants.)
+ * \c PSA_PAKE_PRIMITIVE_TYPE_XXX constants.)
  *
  * J-PAKE can be used with any secure cryptographic hash function. The choice
  * of hash must be supplied to the cipher suite by calling
@@ -1987,7 +1987,7 @@
  *
  * J-PAKE doesn't differentiate between sides and has a distinct identifier
  * associated with each entity. This means that both psa_pake_set_user() and
- * psa_pake_set_peer() needs to be called before commencing the operation.
+ * psa_pake_set_peer() need to be called before commencing the operation.
  * Another consequence is that psa_pake_set_side() is optional and is ignored.
  *
  * The key exchange flow for JPAKE is as follows:
@@ -2038,7 +2038,7 @@
  *      psa_pake_get_implicit_key()
  *
  * For more information consult the documentation of the individual
- * PSA_PAKE_STEP_XXX constants.
+ * \c PSA_PAKE_STEP_XXX constants.
  *
  * J-PAKE is standardised for example in RFC 8236.
  */
@@ -2480,7 +2480,7 @@
  *
  * Although balanced PAKE algorithms are symmetric, some of them needs an
  * ordering of peers for the transcript calculations. If the algorithm does not
- * need this, either #PSA_PAKE_SIDE_FIRST or #PSA_PAKE_SIDE_SECOND are
+ * need this, both #PSA_PAKE_SIDE_FIRST and #PSA_PAKE_SIDE_SECOND are
  * accepted.
  */
 #define PSA_PAKE_SIDE_FIRST                ((psa_pake_side_t)0x01)
@@ -2546,7 +2546,7 @@
  */
 #define PSA_PAKE_PRIMITIVE_TYPE_DH       ((psa_pake_primitive_type_t)0x02)
 
-/** Construct a PAKE primitive from type, family and bitsize.
+/** Construct a PAKE primitive from type, family and bit-size.
  *
  * \param pake_type     The type of the primitive
  *                      (value of type ::psa_pake_primitive_type_t).
@@ -2555,7 +2555,7 @@
  *                      on \p type, for more information consult the
  *                      documentation of individual ::psa_pake_primitive_type_t
  *                      constants).
- * \param pake_bits     The bitsize of the primitive
+ * \param pake_bits     The bit-size of the primitive
  *                      (Value of type \c size_t. The interpretation
  *                      of this parameter depends on \p family, for more
  *                      information consult the documentation of individual