diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index e77b412..bb68d76 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -1141,7 +1141,7 @@
  * \brief           Register callbacks for DTLS cookies
  *                  (Server only. DTLS only.)
  *
- *                  Default: dummy callbacks that fail, to force you to
+ *                  Default: dummy callbacks that fail, in order to force you to
  *                  register working callbacks (and initialize their context).
  *
  *                  To disable HelloVerifyRequest, register NULL callbacks.
@@ -1151,6 +1151,10 @@
  *                  Only disable if you known this can't happen in your
  *                  particular environment.
  *
+ * \note            See comments on \c mbedtls_ssl_handshake() about handling
+ *                  the MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED that is expected
+ *                  on the first handshake attempt when this is enabled.
+ *
  * \param conf              SSL configuration
  * \param f_cookie_write    Cookie write callback
  * \param f_cookie_check    Cookie check callback
@@ -1980,6 +1984,13 @@
  *
  * \return         0 if successful, MBEDTLS_ERR_SSL_WANT_READ,
  *                 MBEDTLS_ERR_SSL_WANT_WRITE, or a specific SSL error code.
+ *
+ * \note           If this function returns non-zero, then the ssl context
+ *                 becomes unusable, and you should either free it or call
+ *                 \c mbedtls_ssl_session_reset() on it before re-using it.
+ *                 If DTLS is in use, then you may choose to handle
+ *                 MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED specially for logging
+ *                 purposes, but you still need to reset/free the context.
  */
 int mbedtls_ssl_handshake( mbedtls_ssl_context *ssl );