Improve mbedtls_platform_zeroize() docs
diff --git a/include/mbedtls/platform_util.h b/include/mbedtls/platform_util.h
index bda9710..84f0732 100644
--- a/include/mbedtls/platform_util.h
+++ b/include/mbedtls/platform_util.h
@@ -34,19 +34,24 @@
/**
* \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 );