docs: more fixes

11 files changed, 90 insertions, 43 deletions

diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index 9dbadb30..019746b3 100644
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -13,7 +13,7 @@ DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
 DOC_SOURCE_DIR=../../libsoup
 
 # Extra options to supply to gtkdoc-scan.
-SCAN_OPTIONS=--rebuild-types
+SCAN_OPTIONS=--rebuild-types --ignore-decorators='SOUP_DEPRECATED\w*\s*\([^)]*\)|SOUP_DEPRECATED\w*|SOUP_AVAILABLE\w*'
 
 # Extra options to supply to gtkdoc-scangobj.
 SCANGOBJ_OPTIONS=
diff --git a/docs/reference/build-howto.xml b/docs/reference/build-howto.xml
index 975dfd55..bec9a454 100644
--- a/docs/reference/build-howto.xml
+++ b/docs/reference/build-howto.xml
@@ -35,41 +35,52 @@ that first appeared in version 2.4") and is essentially just part of
 the package name.
 </para>
 
+</refsect2>
+
+<refsect2>
+<title>API Availability and Deprecation Warnings</title>
+
 <para>
-If you are using any of the GNOME-specific features of
-<application>libsoup</application> (such as automatic proxy
-configuration), you must require
-"<literal>libsoup-gnome-2.4</literal>" instead:
+If you want to restrict your program to a particular
+<application>libsoup</application> version or range of versions, you
+can define <link
+linkend="SOUP-VERSION-MIN-REQUIRED:CAPS"><literal>SOUP_VERSION_MIN_REQUIRED</literal></link>
+and/or <link
+linkend="SOUP-VERSION-MAX-ALLOWED:CAPS"><literal>SOUP_VERSION_MAX_ALLOWED</literal></link>.
+Eg:
 </para>
 
 <informalexample><programlisting>
-PKG_CHECK_MODULES(LIBSOUP, [libsoup-gnome-2.4 >= 2.26])
-AC_SUBST(LIBSOUP_CFLAGS)
-AC_SUBST(LIBSOUP_LIBS)
+LIBSOUP_CFLAGS="$LIBSOUP_CFLAGS -DSOUP_VERSION_MIN_REQUIRED=SOUP_VERSION_2_36"
+LIBSOUP_CFLAGS="$LIBSOUP_CFLAGS -DSOUP_VERSION_MAX_ALLOWED=SOUP_VERSION_2_40"
 </programlisting></informalexample>
 
 <para>
-You can also make <application>libsoup-gnome</application> an optional
-dependency:
+The <literal>SOUP_VERSION_MIN_REQUIRED</literal> declaration states
+that the code is not expected to compile on versions of
+<application>libsoup</application> older than the indicated version
+(here, 2.36), and so the compiler should print warnings if the code
+uses functions that were deprecated as of that release.
 </para>
 
-<informalexample><programlisting>
-PKG_CHECK_MODULES(LIBSOUP_GNOME,
-		  [libsoup-gnome-2.4 >= 2.26],
-		  [LIBSOUP_CFLAGS="$LIBSOUP_GNOME_CFLAGS"
-		   LIBSOUP_LIBS="$LIBSOUP_GNOME_LIBS"
-		   AC_DEFINE(HAVE_LIBSOUP_GNOME, 1, [Have libsoup-gnome])],
-		  [PKG_CHECK_MODULES(LIBSOUP, [libsoup-2.4 >= 2.26])])
-AC_SUBST(LIBSOUP_CFLAGS)
-AC_SUBST(LIBSOUP_LIBS)
-</programlisting></informalexample>
+<para>
+The <literal>SOUP_VERSION_MAX_ALLOWED</literal> declaration states
+that the code <emphasis>is</emphasis> expected to compile on versions
+of <application>libsoup</application> up to the indicated version
+(here, 2.40), and so, when compiling the program against a newer
+version than that, the compiler should print warnings if the code uses
+functions that did not yet exist in the max-allowed release.
+</para>
 
 <para>
-This will allow the application to be built with either plain
-<application>libsoup</application> or with
-<application>libsoup-gnome</application>, and it will define the C
-preprocessor symbol <literal>HAVE_LIBSOUP_GNOME</literal> if
-<application>libsoup-gnome</application> features are available.
+You can use <link
+linkend="SOUP-CHECK-VERSION:CAPS"><literal>SOUP_CHECK_VERSION</literal></link>
+to check the version of libsoup at compile time, to compile different
+code for different <application>libsoup</application> versions. (If
+you are setting <literal>SOUP_VERSION_MIN_REQUIRED</literal> and
+<literal>SOUP_VERSION_MAX_ALLOWED</literal> to different versions, as
+in the example above, then you almost certainly need to be doing
+this.)
 </para>
 
 </refsect2>
@@ -86,18 +97,8 @@ Code using <application>libsoup</application> should do:
 </programlisting></informalexample>
 
 <para>
-or, for <application>libsoup-gnome</application>:
-</para>
-
-<informalexample><programlisting>
-#include &lt;libsoup/soup-gnome.h&gt;
-</programlisting></informalexample>
-
-<para>
-Including individual headers besides the two main header files is not
-recommended. You may include both <literal>soup.h</literal> and
-<literal>soup-gnome.h</literal> (though this is not required; the
-latter automatically includes the former).
+Including individual headers rather than <literal>soup.h</literal> is not
+recommended.
 </para>
 
 </refsect2>
diff --git a/docs/reference/libsoup-2.4-sections.txt b/docs/reference/libsoup-2.4-sections.txt
index 23f55c0f..db45167f 100644
--- a/docs/reference/libsoup-2.4-sections.txt
+++ b/docs/reference/libsoup-2.4-sections.txt
@@ -451,7 +451,6 @@ SOUP_SESSION_GET_CLASS
 SOUP_TYPE_SESSION
 SoupSessionClass
 soup_session_get_type
-soup_request_error_get_type
 soup_request_error_quark
 <SUBSECTION Private>
 SoupConnection
diff --git a/libsoup/soup-cache.c b/libsoup/soup-cache.c
index 6df16655..5569d6b6 100644
--- a/libsoup/soup-cache.c
+++ b/libsoup/soup-cache.c
@@ -39,6 +39,13 @@
 #include "soup-message-private.h"
 #include "soup.h"
 
+/**
+ * SECTION:soup-cache
+ * @short_description: Caching support
+ *
+ * #SoupCache implements a file-based cache for HTTP resources.
+ */
+
 static SoupSessionFeatureInterface *soup_cache_default_feature_interface;
 static void soup_cache_session_feature_init (SoupSessionFeatureInterface *feature_interface, gpointer interface_data);
 
diff --git a/libsoup/soup-proxy-resolver-default.c b/libsoup/soup-proxy-resolver-default.c
index 76e9ff6d..0fc8780c 100644
--- a/libsoup/soup-proxy-resolver-default.c
+++ b/libsoup/soup-proxy-resolver-default.c
@@ -13,10 +13,11 @@
 #include "soup.h"
 
 /**
- * SoupProxyResolverDefault:
+ * SECTION:soup-proxy-resolver-default
+ * @short_description: System proxy configuration integration
  *
- * A #SoupProxyURIResolver implementation that uses the default gio
- * #GProxyResolver to resolve proxies.
+ * #SoupProxyResolverDefault is a #SoupProxyURIResolver implementation
+ * that uses the default gio GProxyResolver to resolve proxies.
  *
  * Since: 2.34
  */
diff --git a/libsoup/soup-proxy-uri-resolver.c b/libsoup/soup-proxy-uri-resolver.c
index 8aecec47..65f65d4b 100644
--- a/libsoup/soup-proxy-uri-resolver.c
+++ b/libsoup/soup-proxy-uri-resolver.c
@@ -12,6 +12,18 @@
 #include "soup-proxy-uri-resolver.h"
 #include "soup.h"
 
+/**
+ * SECTION:soup-proxy-uri-resolver
+ * @short_description: Interface for locating HTTP proxies
+ *
+ * #SoupProxyURIResolver is an interface for finding appropriate HTTP
+ * proxies to use.
+ *
+ * You are not likely to have to implement this interface on your own;
+ * instead, you should usually just be able to use
+ * #SoupProxyResolverDefault.
+ */
+
 G_DEFINE_INTERFACE (SoupProxyURIResolver, soup_proxy_uri_resolver, G_TYPE_OBJECT)
 
 static void
diff --git a/libsoup/soup-request-data.c b/libsoup/soup-request-data.c
index 0ff30c94..66836a5b 100644
--- a/libsoup/soup-request-data.c
+++ b/libsoup/soup-request-data.c
@@ -31,6 +31,13 @@
 #include "soup.h"
 #include "soup-misc-private.h"
 
+/**
+ * SECTION:soup-request-data
+ * @short_description: SoupRequest support for "data" URIs
+ *
+ * #SoupRequestData implements #SoupRequest for "data" URIs.
+ */
+
 G_DEFINE_TYPE (SoupRequestData, soup_request_data, SOUP_TYPE_REQUEST)
 
 struct _SoupRequestDataPrivate {
diff --git a/libsoup/soup-request-file.c b/libsoup/soup-request-file.c
index a71827bb..49b741d0 100644
--- a/libsoup/soup-request-file.c
+++ b/libsoup/soup-request-file.c
@@ -30,6 +30,14 @@
 #include "soup-directory-input-stream.h"
 #include "soup-requester.h"
 
+/**
+ * SECTION:soup-request-file
+ * @short_description: SoupRequest support for "file" and "resource" URIs
+ *
+ * #SoupRequestFile implements #SoupRequest for "file" and "resource"
+ * URIs.
+ */
+
 G_DEFINE_TYPE (SoupRequestFile, soup_request_file, SOUP_TYPE_REQUEST)
 
 struct _SoupRequestFilePrivate {
diff --git a/libsoup/soup-request-http.c b/libsoup/soup-request-http.c
index 871ca0ea..e932217a 100644
--- a/libsoup/soup-request-http.c
+++ b/libsoup/soup-request-http.c
@@ -32,6 +32,18 @@
 #include "soup-message-private.h"
 #include "soup-session-private.h"
 
+/**
+ * SECTION:soup-request-http
+ * @short_description: SoupRequest support for "http" and "https" URIs
+ *
+ * #SoupRequestHTTP implements #SoupRequest for "http" and "https"
+ * URIs.
+ *
+ * To do more complicated HTTP operations using the #SoupRequest APIs,
+ * call soup_request_http_get_message() to get the request's
+ * #SoupMessage.
+ */
+
 G_DEFINE_TYPE (SoupRequestHTTP, soup_request_http, SOUP_TYPE_REQUEST)
 
 /**
diff --git a/libsoup/soup-session.h b/libsoup/soup-session.h
index ca5060ee..b64fcaeb 100644
--- a/libsoup/soup-session.h
+++ b/libsoup/soup-session.h
@@ -103,7 +103,7 @@ void            soup_session_cancel_message   (SoupSession           *session,
 					       guint                  status_code);
 void            soup_session_abort            (SoupSession           *session);
 
-SOUP_AVAILABLE_IN_2_30
+/* SOUP_AVAILABLE_IN_2_30 -- this trips up gtkdoc-scan */
 SOUP_DEPRECATED_IN_2_38_FOR (soup_session_prefetch_dns)
 void            soup_session_prepare_for_uri  (SoupSession           *session,
 					       SoupURI               *uri);
diff --git a/libsoup/soup-value-utils.c b/libsoup/soup-value-utils.c
index b929544b..e1f7c92f 100644
--- a/libsoup/soup-value-utils.c
+++ b/libsoup/soup-value-utils.c
@@ -15,7 +15,7 @@
 
 /**
  * SECTION:soup-value-utils
- * @short_description: #GValue utilities
+ * @short_description: GValue utilities
  *
  * These methods are useful for manipulating #GValue<!-- -->s, and in
  * particular, arrays and hash tables of #GValue<!-- -->s, in a