PSA PAKE: improve documentation
Signed-off-by: Janos Follath <janos.follath@arm.com>
diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index e4a21d4..c5ae099 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -839,9 +839,10 @@
* - The group can be either an elliptic curve or defined over a finite field.
* - Schnorr NIZK proof as defined by RFC 8235 and using the same group as the
* J-PAKE algorithm.
- * - A secure cryptographic hash function.
+ * - A cryptographic hash function.
*
- * To select these parameters and set up the cipher suite, call
+ * To select these parameters and set up the cipher suite, call these functions
+ * in any order:
*
* \code
* psa_pake_cs_set_algorithm(cipher_suite, PSA_ALG_JPAKE);
@@ -1499,8 +1500,8 @@
* yet).
* \param side A value of type ::psa_pake_side_t signaling the
* side of the algorithm that is being set up. For
- * more information see the documentation of \c
- * PSA_PAKE_SIDE_XXX constants.
+ * more information see the documentation of
+ * \c PSA_PAKE_SIDE_XXX constants.
*
* \retval #PSA_SUCCESS
* Success.
@@ -1652,8 +1653,8 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (it must be active, but beyond that
- * validity is specific to the algorithm).
+ * The PAKE operation state is not valid (it must be active, but beyond
+ * that validity is specific to the algorithm).
* \retval #PSA_ERROR_BAD_STATE
* The state of \p output is not valid for
* the #PSA_KEY_DERIVATION_INPUT_SECRET step. This can happen if the
@@ -1685,7 +1686,7 @@
*
* See also #PSA_PAKE_OUTPUT_MAX_SIZE
*
- * \param alg A PAKE algorithm (PSA_ALG_XXX value such that
+ * \param alg A PAKE algorithm (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_PAKE(\p alg) is true).
* \param primitive A primitive of type ::psa_pake_primitive_t that is
* compatible with algorithm \p alg.
@@ -1706,7 +1707,7 @@
*
* See also #PSA_PAKE_INPUT_MAX_SIZE
*
- * \param alg A PAKE algorithm (PSA_ALG_XXX value such that
+ * \param alg A PAKE algorithm (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_PAKE(\p alg) is true).
* \param primitive A primitive of type ::psa_pake_primitive_t that is
* compatible with algorithm \p alg.