Fix typos, grammar and wording in documentation
diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h
index 53db082..6bb0098 100644
--- a/include/mbedtls/config.h
+++ b/include/mbedtls/config.h
@@ -1311,20 +1311,20 @@
/**
* \def MBEDTLS_SSL_CONTEXT_SERIALIZATION
*
- * Enable the APIs for serialization of a full SSL context:
- * mbedtls_ssl_context_save() and mbedtls_ssl_context_load().
+ * Enable serialization of the TLS context structures, through use of the
+ * functions mbedtls_ssl_context_save() and mbedtls_ssl_context_load().
*
* This pair of functions allows one side of a connection to serialize the
* context associated with the connection, then free or re-use that context
* while the serialized state is persisted elsewhere, and finally deserialize
* that state to a live context for resuming read/write operations on the
- * connection, in a way that's transparent to the peer, since from a protocol
- * point of view, the state of the connection is unaffected.
+ * connection. From a protocol perspective, the state of the connection is
+ * unaffected, in particular this is entirely transparent to the peer.
*
* Note: this is distinct from TLS session resumption, which is part of the
* protocol and fully visible by the peer. TLS session resumption enables
* establishing new connections associated to a saved session with shorter,
- * lighter handshakes, while context serialization is a local optimisation in
+ * lighter handshakes, while context serialization is a local optimization in
* handling a single, potentially long-lived connection.
*
* Enabling these APIs makes some SSL structures larger, as 64 extra bytes are
diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index 4f64102..536c0a7 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -3553,24 +3553,25 @@
void mbedtls_ssl_free( mbedtls_ssl_context *ssl );
/**
- * \brief Save a live connection as serialized data in a buffer.
- * This allows to free or re-use the SSL context while still
- * picking up the connection later in a way that it entirely
- * transparent to the peer.
+ * \brief Save an active connection as serialized data in a buffer.
+ * This allows the freeing or re-using of the SSL context
+ * while still picking up the connection later in a way that
+ * it entirely transparent to the peer.
*
* \see mbedtls_ssl_context_load()
*
* \note This feature is currently only available under certain
- * conditions, see the documentation of return value
+ * conditions, see the documentation of the return value
* #MBEDTLS_ERR_SSL_BAD_INPUT_DATA for details.
*
- * \note When the function succeeds, it calls
+ * \note When this function succeeds, it calls
* mbedtls_ssl_session_reset() on \p ssl which as a result is
* no longer associated with the connection that has been
- * serialized. This avoid creating copies of the session
+ * serialized. This avoids creating copies of the session
* state. You're then free to either re-use the context
* structure for a different connection, or call
- * mbedtls_ssl_session_free() on it.
+ * mbedtls_ssl_session_free() on it. See the documentation of
+ * mbedtls_ssl_session_reset() for more details.
*
* \param ssl The SSL context to save. On success, it is no longer
* associated with the connection that has been serialized.
@@ -3588,7 +3589,7 @@
*
* \return \c 0 if successful.
* \return #MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL if \p buf is too small.
- * \return #MBEDTLS_ERR_SSL_BAD_INPUT_DATA if a handsahke is in
+ * \return #MBEDTLS_ERR_SSL_BAD_INPUT_DATA if a handshake is in
* progress, or there is pending data for reading or sending,
* or the connection does not use DTLS 1.2 with and AEAD
* ciphersuite, or renegotiation is enabled.
@@ -3618,10 +3619,13 @@
* calling mbedtls_ssl_session_reset() on a context that was
* previously prepared as above but used in the meantime.
*
- * \note After calling this function sucessfully, you still need to
- * configure some connection-specific callback and settings
- * before you can use the connection again. Specifically, you
- * want to call at least mbedtls_ssl_set_bio() and possibly
+ * \note Before or after calling this function successfully, you
+ * also need to configure some connection-specific callback
+ * and settings before you can use the connection again
+ * (unless they were already set before calling
+ * mbedtls_ssl_session_reset() and the values are suitable for
+ * the present connection). Specifically, you want to call
+ * at least mbedtls_ssl_set_bio() and possibly
* mbedtls_ssl_set_timer_cb(). You might also want to call
* mbedtls_ssl_set_mtu() if new information about the PMTU is
* available - otherwise the saved information will be used.