[libsoup] Clarify the meaning of #SoupSession:ssl-strict

[Dan Winship <danw src gnome org>]

commit 878808be848128213d13c3041848ddfffa998a5d
Author: Dan Winship <danw gnome org>
Date:   Fri Dec 16 09:08:13 2011 -0500

    Clarify the meaning of #SoupSession:ssl-strict
    
    and fix the Since tags on #SoupSession:ssl-use-system-ca-file
    and #SoupSession:tlsdb
    
    https://bugzilla.gnome.org/show_bug.cgi?id=666280

 libsoup/soup-session.c |   55 ++++++++++++++++++++++++++++++++---------------
 1 files changed, 37 insertions(+), 18 deletions(-)
---
diff --git a/libsoup/soup-session.c b/libsoup/soup-session.c
index 3babab4..32c1b30 100644
--- a/libsoup/soup-session.c
+++ b/libsoup/soup-session.c
@@ -587,13 +587,10 @@ soup_session_class_init (SoupSessionClass *session_class)
 	/**
 	 * SOUP_SESSION_USE_SYSTEM_CA_FILE:
 	 *
-	 * Alias for the #SoupSession:ssl-use-system-ca-file property.
-	 * Setting this to %TRUE overrides #SoupSession:ssl-ca-file
-	 * and #SoupSession:tls-database, and uses the default system
-	 * CA database (which, despite the name, may not actually be a
-	 * file).
+	 * Alias for the #SoupSession:ssl-use-system-ca-file property,
+	 * qv.
 	 *
-	 * Since: 2.36
+	 * Since: 2.38
 	 **/
 	/**
 	 * #SoupSession:ssl-use-system-ca-file:
@@ -603,7 +600,10 @@ soup_session_class_init (SoupSessionClass *session_class)
 	 * CA database (which, despite the name, may not actually be a
 	 * file).
 	 *
-	 * Since: 2.36
+	 * See #SoupSession:ssl-strict for more information on how
+	 * https certificate validation is handled.
+	 *
+	 * Since: 2.38
 	 **/
 	g_object_class_install_property (
 		object_class, PROP_SSL_USE_SYSTEM_CA_FILE,
@@ -615,12 +615,9 @@ soup_session_class_init (SoupSessionClass *session_class)
 	/**
 	 * SOUP_SESSION_TLS_DATABASE:
 	 *
-	 * Alias for the #SoupSession:tls-database property. Overrides
-	 * #SoupSession:ssl-ca-file and
-	 * #SoupSession:ssl-use-system-ca-file, and uses the provided
-	 * #GTlsDatabase.
+	 * Alias for the #SoupSession:tls-database property, qv.
 	 *
-	 * Since: 2.36
+	 * Since: 2.38
 	 **/
 	/**
 	 * #SoupSession:tls-database:
@@ -629,7 +626,10 @@ soup_session_class_init (SoupSessionClass *session_class)
 	 * #SoupSession:ssl-use-system-ca-file, and uses the provided
 	 * #GTlsDatabase.
 	 *
-	 * Since: 2.36
+	 * See #SoupSession:ssl-strict for more information on how
+	 * https certificate validation is handled.
+	 *
+	 * Since: 2.38
 	 **/
 	g_object_class_install_property (
 		object_class, PROP_TLS_DATABASE,
@@ -641,14 +641,33 @@ soup_session_class_init (SoupSessionClass *session_class)
 	/**
 	 * SOUP_SESSION_SSL_STRICT:
 	 *
-	 * Alias for the #SoupSession:ssl-strict property. By default,
-	 * when validating certificates against a CA file, Soup will
-	 * consider invalid certificates as a connection error.
-	 * Setting this property to %TRUE makes soup ignore the
-	 * errors, and make the connection.
+	 * Alias for the #SoupSession:ssl-strict property, qv.
 	 *
 	 * Since: 2.30
 	 **/
+	/**
+	 * SoupSession:ssl-strict:
+	 *
+	 * Normally, if #SoupSession:ssl-ca-file (or
+	 * #SoupSession:tlsdb or #SoupSession:ssl-use-system-ca-file)
+	 * is set, then libsoup will reject any certificate that is
+	 * invalid (ie, expired) or that is not signed by one of the
+	 * given CA certificates, and the #SoupMessage will fail with
+	 * the status %SOUP_STATUS_SSL_FAILED.
+	 *
+	 * If you set #SoupSession:ssl-strict to %FALSE, then all
+	 * certificates will be accepted, and you will need to call
+	 * soup_message_get_https_status() to distinguish valid from
+	 * invalid certificates. (This can be used, eg, if you want to
+	 * accept invalid certificates after giving some sort of
+	 * warning.)
+	 *
+	 * If the session has no CA file or TLS database, then all
+	 * certificates are always accepted, and this property has no
+	 * effect.
+	 *
+	 * Since: 2.30
+	 */
 	g_object_class_install_property (
 		object_class, PROP_SSL_STRICT,
 		g_param_spec_boolean (SOUP_SESSION_SSL_STRICT,