diff --git a/offlineimap.conf b/offlineimap.conf
index a84606a..34717de 100644
--- a/offlineimap.conf
+++ b/offlineimap.conf
@@ -828,8 +828,15 @@ remoteuser = username
 #
 # XOAUTH2 authentication (for instance, to use with Gmail).
 #
-# This option was tested on Gmail only, but should work
-# with type = IMAP for compatible servers.
+# This option was tested on Gmail only, but should work with type = IMAP for
+# compatible servers.
+#
+# For Gmail (and maybe others), XOAUTH2 requires ssl. This means that STARTTLS
+# won't work and that Offlineimap will perform certificate validation.  IOW, the
+# following configuration is used:
+#   - sslcacertfile: MUST BE correclty configured
+#   - ssl = yes (optional, will be used anyway)
+#   - starttls = no (optional, will be tried but won't work anyway)
 #
 # Mandatory parameters are "oauth2_client_id", "oauth2_client_secret" and
 # either "oauth2_refresh_token" or "oauth2_access_token". XOAUTH2 mechanism
@@ -855,7 +862,7 @@ remoteuser = username
 # The return values must be bytes.
 #oauth2_client_id_eval = get_client_id("accountname")
 #oauth2_client_secret_eval = get_client_secret("accountname")
-
+#
 # Specify the refresh token to use for the connection to the mail server.
 # Here's an example of a way to get a refresh token:
 #    - Clone this project: https://github.com/google/gmail-oauth2-tools
@@ -873,6 +880,7 @@ remoteuser = username
 # If you want to use a refresh token, make sure you disabled/removed any
 # oauth2_access_token option. The access token is downloaded from the URL
 # defined in the oauth2_request_url configuration option.
+#
 # If the type of the remote is IMAP, oauth2_request_url MUST be defined.
 # For Gmail, the default URL is https://accounts.google.com/o/oauth2/token.
 #