Improve mbedtls_platform_zeroize() docs

include/mbedtls/platform_util.h

@@ -34,19 +34,24 @@ extern "C" {
 /**
  * \brief       Securely zeroize a buffer
  *
- * \param buf   Buffer to be zeroized
- * \param len   Length of the buffer in bytes
+ *              The function is meant to wipe the data contained in a buffer so
+ *              that it can no longer be recovered even if the program memory
+ *              is later compromised. Call this function on sensitive data
+ *              stored on the stack before returning from a function, and on
+ *              sensitive data stored on the heap before freeing the heap
+ *              object.
  *
- * \note        This implementation should never be optimized out by the
- *              compiler
- *
- * \note        It is extremely difficult to guarantee that calls to
+ *              It is extremely difficult to guarantee that calls to
  *              mbedtls_platform_zeroize() are not removed by aggressive
  *              compiler optimizations in a portable way. For this reason, Mbed
  *              TLS provides the configuration option
  *              MBEDTLS_PLATFORM_ZEROIZE_ALT, which allows users to configure
  *              mbedtls_platform_zeroize() to use a suitable implementation for
  *              their platform and needs
+ *
+ * \param buf   Buffer to be zeroized
+ * \param len   Length of the buffer in bytes
+ *
  */
 void mbedtls_platform_zeroize( void *buf, size_t len );