Address review comments for documentation
diff --git a/include/mbedtls/platform_util.h b/include/mbedtls/platform_util.h
index 35e3976..586f0d9 100644
--- a/include/mbedtls/platform_util.h
+++ b/include/mbedtls/platform_util.h
@@ -167,12 +167,11 @@
/**
* \brief Secure memset
*
- * This function is meant to provide a more secure way to do
- * memset. It starts by initialising the given memory area
- * from random tail location with random data. After tail is
- * initialised, the remaining head of the buffer is initialised
- * with random data. After initialisation, the original memset
- * is performed
+ * This is a constant-time version of memset(). If
+ * MBEDTLS_ENTROPY_HARDWARE_ALT is defined, the buffer is
+ * initialised with random data and the order is also
+ * randomised using the hardware RNG in order to further harden
+ * against side-channel attacks.
*
* \param ptr Buffer to be set.
* \param value Value to be used when setting the buffer.
@@ -185,12 +184,11 @@
/**
* \brief Secure memcpy
*
- * This function is meant to provide a more secure way to do
- * memcpy. It starts by initialising the given memory area
- * with random data. After initialisation, the original memcpy
- * is performed by starting first copying from random tail
- * location of the buffer. After tail has been copied, the
- * remaining head is copied as well.
+ * This is a constant-time version of memcpy(). If
+ * MBEDTLS_ENTROPY_HARDWARE_ALT is defined, the buffer is
+ * initialised with random data and the order is also
+ * randomised using the hardware RNG in order to further harden
+ * against side-channel attacks.
*
* \param dst Destination buffer where the data is being copied to.
* \param src Source buffer where the data is being copied from.
@@ -203,18 +201,17 @@
/**
* \brief Secure memcmp
*
- * This function is meant to provide a more secure way to do
- * memcmp. It starts comparing from a random offset and goes
- * through the tail part of buffers first byte by byte. After
- * that it starts going through the head part of buffer. In the
- * end, the number of equal bytes is compared to the length of the
- * buffers, thus making the function a fixed time memcmp.
+ * This is a constant-time version of memcmp(). If
+ * MBEDTLS_ENTROPY_HARDWARE_ALT is defined, the order is also
+ * randomised using the hardware RNG in order to further harden
+ * against side-channel attacks.
*
* \param buf1 First buffer to compare.
* \param buf2 Second buffer to compare against.
* \param num The length of the buffers in bytes.
*
- * \return 0 if the buffers were equal.
+ * \return 0 if the buffers were equal or an unspecified non-zero value
+ * otherwise.
*/
int mbedtls_platform_memcmp( const void *buf1, const void *buf2, size_t num );