diff --git a/gio/gtlsconnection.c b/gio/gtlsconnection.c
index e13d98614..b0353af9d 100644
--- a/gio/gtlsconnection.c
+++ b/gio/gtlsconnection.c
@@ -674,7 +674,8 @@ g_tls_connection_get_require_close_notify (GTlsConnection *conn)
  * @conn: a #GTlsConnection
  * @mode: the rehandshaking mode
  *
- * Sets how @conn behaves with respect to rehandshaking requests.
+ * Sets how @conn behaves with respect to rehandshaking requests, when
+ * TLS 1.2 or older is in use.
  *
  * %G_TLS_REHANDSHAKE_NEVER means that it will never agree to
  * rehandshake after the initial handshake is complete. (For a client,
@@ -756,7 +757,8 @@ g_tls_connection_get_rehandshake_mode (GTlsConnection       *conn)
  * the beginning of the communication, you do not need to call this
  * function explicitly unless you want clearer error reporting.
  * However, you may call g_tls_connection_handshake() later on to
- * renegotiate parameters (encryption methods, etc) with the client.
+ * rehandshake, if TLS 1.2 or older is in use. With TLS 1.3, this will
+ * instead perform a rekey.
  *
  * #GTlsConnection::accept_certificate may be emitted during the
  * handshake.