Document potential footgun with GTlsCertificateFlags

Once upon a time, we tried to return all possible certificate errors,
but it never actually worked reliably and nowadays we have given up.
This needs to be documented because a reasonable developer would not
expect it.

Because mistakes could be security-critical, I decided to copy the same
warning in several different places rather than relying only on
cross-referencese.

gio/gtlsconnection.c

@@ -248,6 +248,14 @@ g_tls_connection_class_init (GTlsConnectionClass *klass)
    * #GTlsConnection::accept-certificate overrode the default
    * behavior.
    *
+   * GLib guarantees that if certificate verification fails, at least
+   * one error will be set, but it does not guarantee that all possible
+   * errors will be set. Accordingly, you may not safely decide to
+   * ignore any particular type of error. For example, it would be
+   * incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow
+   * expired certificates, because this could potentially be the only
+   * error flag set even if other problems exist with the certificate.
+   *
    * Since: 2.28
    */
   g_object_class_install_property (gobject_class, PROP_PEER_CERTIFICATE_ERRORS,
@@ -339,6 +347,15 @@ g_tls_connection_class_init (GTlsConnectionClass *klass)
    * signal handler. Otherwise, if no handler accepts the certificate,
    * the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE.
    *
+   * GLib guarantees that if certificate verification fails, this signal
+   * will be emitted with at least one error will be set in @errors, but
+   * it does not guarantee that all possible errors will be set.
+   * Accordingly, you may not safely decide to ignore any particular
+   * type of error. For example, it would be incorrect to ignore
+   * %G_TLS_CERTIFICATE_EXPIRED if you want to allow expired
+   * certificates, because this could potentially be the only error flag
+   * set even if other problems exist with the certificate.
+   *
    * For a server-side connection, @peer_cert is the certificate
    * presented by the client, if this was requested via the server's
    * #GTlsServerConnection:authentication_mode. On the server side,
@@ -655,6 +672,8 @@ g_tls_connection_get_peer_certificate (GTlsConnection *conn)
  * certificate, after the handshake has completed or failed. (It is
  * not set during the emission of #GTlsConnection::accept-certificate.)
  *
+ * See #GTlsConnection:peer-certificate-errors for more information.
+ *
  * Returns: @conn's peer's certificate errors
  *
  * Since: 2.28