Documentation: fix \p names that diverged from the code
Fix places where Doxygen documentation uses \p to refer to a parameter
name and where the name used did not match the actual parameter name.
I used the following script to detect problematic cases:
```
perl -w -ne 'if (eof) { $. = 0; } if (m!^/\*\*!) { $in_doc = 1; %param = (); %p = (); } if (m!\*/!) { foreach $name (keys %p) { if (!$param{$name}) { foreach $line (@{$p{$name}}) { print "$ARGV:$line: $name\n" } } } $in_doc = 0; } if ($in_doc) { if (/\\param(?: *\[[^\[\]]*\])? +(\w+)/) { $param{$1} = 1; } foreach (/\\p +\*?(\w+)/) { push @{$p{$1}}, $.; } }' include/psa/*.h
```
This commits fixes all the remaining occurrences under include/psa,
which were just trivial name mismatches.
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
diff --git a/include/psa/crypto_compat.h b/include/psa/crypto_compat.h
index 66e6201..ae09a70 100644
--- a/include/psa/crypto_compat.h
+++ b/include/psa/crypto_compat.h
@@ -313,9 +313,9 @@
* number of open keys, the number of open key handles, or available
* memory.
* \retval #PSA_ERROR_DOES_NOT_EXIST
- * There is no persistent key with key identifier \p id.
+ * There is no persistent key with key identifier \p key.
* \retval #PSA_ERROR_INVALID_ARGUMENT
- * \p id is not a valid persistent key identifier.
+ * \p key is not a valid persistent key identifier.
* \retval #PSA_ERROR_NOT_PERMITTED
* The specified key exists, but the application does not have the
* permission to access it. Note that this specification does not
diff --git a/include/psa/crypto_se_driver.h b/include/psa/crypto_se_driver.h
index f6e3022..aaf117f 100644
--- a/include/psa/crypto_se_driver.h
+++ b/include/psa/crypto_se_driver.h
@@ -1365,16 +1365,16 @@
*
* \return #PSA_SUCCESS
* The driver was successfully registered. Applications can now
- * use \p lifetime to access keys through the methods passed to
+ * use \p location to access keys through the methods passed to
* this function.
* \return #PSA_ERROR_BAD_STATE
* This function was called after the initialization of the
* cryptography module, and this implementation does not support
* driver registration at this stage.
* \return #PSA_ERROR_ALREADY_EXISTS
- * There is already a registered driver for this value of \p lifetime.
+ * There is already a registered driver for this value of \p location.
* \return #PSA_ERROR_INVALID_ARGUMENT
- * \p lifetime is a reserved value.
+ * \p location is a reserved value.
* \return #PSA_ERROR_NOT_SUPPORTED
* `methods->hal_version` is not supported by this implementation.
* \return #PSA_ERROR_INSUFFICIENT_MEMORY
diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h
index c2a2770..24b2e18 100644
--- a/include/psa/crypto_values.h
+++ b/include/psa/crypto_values.h
@@ -892,7 +892,7 @@
* for policy comparison purposes.
*
* \param mac_alg A MAC algorithm identifier (value of type
- * #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p alg)
+ * #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p mac_alg)
* is true). This may be a truncated or untruncated
* MAC algorithm.
* \param mac_length Desired length of the truncated MAC in bytes.
@@ -903,7 +903,7 @@
*
* \return The corresponding MAC algorithm with the specified
* length.
- * \return Unspecified if \p alg is not a supported
+ * \return Unspecified if \p mac_alg is not a supported
* MAC algorithm or if \p mac_length is too small or
* too large for the specified MAC algorithm.
*/
@@ -916,12 +916,12 @@
* MAC algorithm.
*
* \param mac_alg A MAC algorithm identifier (value of type
- * #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p alg)
+ * #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p mac_alg)
* is true). This may be a truncated or untruncated
* MAC algorithm.
*
* \return The corresponding base MAC algorithm.
- * \return Unspecified if \p alg is not a supported
+ * \return Unspecified if \p mac_alg is not a supported
* MAC algorithm.
*/
#define PSA_ALG_FULL_LENGTH_MAC(mac_alg) \
@@ -931,12 +931,12 @@
/** Length to which a MAC algorithm is truncated.
*
* \param mac_alg A MAC algorithm identifier (value of type
- * #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p alg)
+ * #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p mac_alg)
* is true).
*
* \return Length of the truncated MAC in bytes.
- * \return 0 if \p alg is a non-truncated MAC algorithm.
- * \return Unspecified if \p alg is not a supported
+ * \return 0 if \p mac_alg is a non-truncated MAC algorithm.
+ * \return Unspecified if \p mac_alg is not a supported
* MAC algorithm.
*/
#define PSA_MAC_TRUNCATED_LENGTH(mac_alg) \
@@ -1146,13 +1146,13 @@
* of the ciphertext.
*
* \param aead_alg An AEAD algorithm identifier (value of type
- * #psa_algorithm_t such that #PSA_ALG_IS_AEAD(\p alg)
+ * #psa_algorithm_t such that #PSA_ALG_IS_AEAD(\p aead_alg)
* is true).
* \param tag_length Desired length of the authentication tag in bytes.
*
* \return The corresponding AEAD algorithm with the specified
* length.
- * \return Unspecified if \p alg is not a supported
+ * \return Unspecified if \p aead_alg is not a supported
* AEAD algorithm or if \p tag_length is not valid
* for the specified AEAD algorithm.
*/
@@ -1165,11 +1165,11 @@
/** Retrieve the tag length of a specified AEAD algorithm
*
* \param aead_alg An AEAD algorithm identifier (value of type
- * #psa_algorithm_t such that #PSA_ALG_IS_AEAD(\p alg)
+ * #psa_algorithm_t such that #PSA_ALG_IS_AEAD(\p aead_alg)
* is true).
*
* \return The tag length specified by the input algorithm.
- * \return Unspecified if \p alg is not a supported
+ * \return Unspecified if \p aead_alg is not a supported
* AEAD algorithm.
*/
#define PSA_ALG_AEAD_GET_TAG_LENGTH(aead_alg) \
@@ -1179,7 +1179,7 @@
/** Calculate the corresponding AEAD algorithm with the default tag length.
*
* \param aead_alg An AEAD algorithm (\c PSA_ALG_XXX value such that
- * #PSA_ALG_IS_AEAD(\p alg) is true).
+ * #PSA_ALG_IS_AEAD(\p aead_alg) is true).
*
* \return The corresponding AEAD algorithm with the default
* tag length for that algorithm.