diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index 4471de507..35f4d320a 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -1388,6 +1388,10 @@ void mbedtls_ssl_set_bio( mbedtls_ssl_context *ssl,
  *                 the maximum size datagram the DTLS layer will pass to the
  *                 \c f_send() callback set using \c mbedtls_ssl_set_bio().
  *
+ * \note           The limit on datagram size is converted to a limit on
+ *                 record payload by subtracting the current overhead of
+ *                 encapsulation and encryption/authentication if any.
+ *
  * \note           This can be called at any point during the connection, for
  *                 example when a PMTU estimate becomes available from other
  *                 sources, such as lower (or higher) protocol layers.
@@ -1400,14 +1404,12 @@ void mbedtls_ssl_set_bio( mbedtls_ssl_context *ssl,
  *
  * \note           If both a MTU and a maximum fragment length have been
  *                 configured (or negotiated with the peer), the resulting
- *                 lower limit (after translating the MTU setting to a limit
- *                 on the record content length) is used.
+ *                 lower limit on record payload (see first note) is used.
  *
  * \note           This can only be used to decrease the maximum size
- *                 of datagrams (hence records, as records cannot span
- *                 multiple datagrams) sent. It cannot be used to increase the
- *                 maximum size of records over the limit set by
- *                 #MBEDTLS_SSL_OUT_CONTENT_LEN.
+ *                 of datagrams (hence records, see first note) sent. It
+ *                 cannot be used to increase the maximum size of records over
+ *                 the limit set by #MBEDTLS_SSL_OUT_CONTENT_LEN.
  *
  * \note           Values lower than the current record layer expansion will
  *                 result in an error when trying to send data.