Documentation clarifications
Clarify or add the documentation of some functions and constants.
Add a note about what the __DOXYGEN_ONLY__ section is for.
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 7eb45fb..48586a2 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -11,6 +11,11 @@
#include <stddef.h>
#ifdef __DOXYGEN_ONLY__
+/* This __DOXYGEN_ONLY__ block contains mock definitions for things that
+ * must be defined in the crypto_platform.h header. These mock definitions
+ * are present in this file as a convenience to generate pretty-printed
+ * documentation that includes those definitions. */
+
/** \defgroup platform Implementation-specific definitions
* @{
*/
@@ -30,7 +35,7 @@
typedef _unsigned_integral_type_ psa_key_slot_t;
/**@}*/
-#endif
+#endif /* __DOXYGEN_ONLY__ */
#ifdef __cplusplus
extern "C" {
@@ -120,7 +125,19 @@
*/
typedef uint32_t psa_key_type_t;
+/** An invalid key type value.
+ *
+ * Zero is not the encoding of any key type.
+ */
#define PSA_KEY_TYPE_NONE ((psa_key_type_t)0x00000000)
+
+/** Vendor-defined flag
+ *
+ * Key types defined by this standard will never have the
+ * #PSA_KEY_TYPE_VENDOR_FLAG bit set. Vendors who define additional key types
+ * must use an encoding with the #PSA_KEY_TYPE_VENDOR_FLAG bit set and should
+ * respect the bitwise structure used by standard encodings whenever practical.
+ */
#define PSA_KEY_TYPE_VENDOR_FLAG ((psa_key_type_t)0x80000000)
#define PSA_KEY_TYPE_CATEGORY_MASK ((psa_key_type_t)0x7e000000)
@@ -142,6 +159,7 @@
#define PSA_KEY_TYPE_ECC_BASE ((psa_key_type_t)0x06030000)
#define PSA_KEY_TYPE_ECC_CURVE_MASK ((psa_key_type_t)0x0000ffff)
+/** Whether a key type is vendor-defined. */
#define PSA_KEY_TYPE_IS_VENDOR_DEFINED(type) \
(((type) & PSA_KEY_TYPE_VENDOR_FLAG) != 0)
#define PSA_KEY_TYPE_IS_RAW_BYTES(type) \
@@ -290,7 +308,8 @@
/**
* \brief Import a key in binary format.
*
- * This function supports any output from psa_export_key().
+ * This function supports any output from psa_export_key(). Refer to the
+ * documentation of psa_export_key() for the format for each key type.
*
* \param key Slot where the key will be stored. This must be a
* valid slot for a key of the chosen type. It must