Improve docs for mbedtls_ct_compiler_opaque
Signed-off-by: Dave Rodgman <dave.rodgman@arm.com>
diff --git a/library/constant_time_impl.h b/library/constant_time_impl.h
index 191769b..b2ef73f 100644
--- a/library/constant_time_impl.h
+++ b/library/constant_time_impl.h
@@ -68,6 +68,19 @@
extern volatile mbedtls_ct_uint_t mbedtls_ct_zero;
#endif
+/**
+ * \brief Ensure that a value cannot be known at compile time.
+ *
+ * \param x The value to hide from the compiler.
+ * \return The same value that was passed in, such that the compiler
+ * cannot prove its value (even for calls of the form
+ * x = mbedtls_ct_compiler_opaque(1), x will be unknown).
+ *
+ * \note This is mainly used in constructing mbedtls_ct_condition_t
+ * values and performing operations over them, to ensure that
+ * there is no way for the compiler to ever know anything about
+ * the value of an mbedtls_ct_condition_t.
+ */
static inline mbedtls_ct_uint_t mbedtls_ct_compiler_opaque(mbedtls_ct_uint_t x)
{
#if defined(MBEDTLS_CT_ASM)
diff --git a/library/constant_time_internal.h b/library/constant_time_internal.h
index 79927c1..c15eaeb 100644
--- a/library/constant_time_internal.h
+++ b/library/constant_time_internal.h
@@ -53,8 +53,9 @@
* function.
* example: if (x) memcpy(...) => mbedtls_ct_memcpy_if(x, ...)
*
- * mbedtls_ct_condition_t should be treated as opaque and only manipulated
- * via the functions in this header.
+ * mbedtls_ct_condition_t must be treated as opaque and only created and
+ * manipulated via the functions in this header. The compiler should never
+ * be able to prove anything about its value at compile-time.
*
* mbedtls_ct_uint_t is an unsigned integer type over which constant time
* operations may be performed via the functions in this header. It is as big