Improve docs for mbedtls_ct_compiler_opaque

Signed-off-by: Dave Rodgman <dave.rodgman@arm.com>

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)

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