From 00115034ea00d8df8d3c009c4e76e98cb1dd893d Mon Sep 17 00:00:00 2001
From: Ron Eldor <Ron.Eldor@arm.com>
Date: Tue, 17 Jul 2018 11:21:50 +0300
Subject: [PATCH] Repharse comments

Rephrase comments to clarify them.
---
 include/mbedtls/ssl.h | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index 4c9f9e839..8b6e0491e 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -2746,10 +2746,16 @@ const mbedtls_x509_crt *mbedtls_ssl_get_peer_cert( const mbedtls_ssl_context *ss
  *                 MBEDTLS_ERR_SSL_BAD_INPUT_DATA if used server-side or
  *                 arguments are otherwise invalid.
  *
- * \note           Only the server certificate is copied, and not the chain
- *                 but this is not a problem because the result of the chain
- *                 verification is stored in `verify_result` and can be checked
- *                 with \c mbedtls_ssl_get_verify_result().
+ * \note           Only the server certificate is copied, and not the full chain,
+ *                 so you should not attempt to validate the certificate again
+ *                 by calling \c mbedtls_x509_crt_verify() on it.
+ *                 Instead, you should use the results from the verification
+ *                 in the original handshake by calling \c mbedtls_ssl_get_verify_result()
+ *                 after loading the session again into a new SSL context
+ *                 using \c mbedtls_ssl_set_session().
+ *
+ * \note           Once the session object is not needed anymore, you should
+ *                 free it by calling \c mbedtls_ssl_session_free().
  *
  * \sa             mbedtls_ssl_set_session()
  */
@@ -3027,6 +3033,9 @@ void mbedtls_ssl_session_init( mbedtls_ssl_session *session );
  * \brief          Free referenced items in an SSL session including the
  *                 peer certificate and clear memory
  *
+ * \note           A session object can be freed even if the SSL context
+ *                 that was used to retrieve the session is still in use.
+ *
  * \param session  SSL session
  */
 void mbedtls_ssl_session_free( mbedtls_ssl_session *session );