Misc docs updates

14 files changed, 84 insertions, 65 deletions

diff --git a/.gitignore b/.gitignore
index 713357b9..293106cf 100644
--- a/.gitignore
+++ b/.gitignore
@@ -16,6 +16,7 @@ config.log
 config.status
 configure
 docs/reference/*.stamp
+docs/reference/*.bak
 docs/reference/html
 docs/reference/libsoup-2.4-decl-list.txt
 docs/reference/libsoup-2.4-decl.txt
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index a11ce395..d47693a1 100644
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -44,7 +44,8 @@ IGNORE_HFILES= soup.h soup-enum-types.h \
 	soup-cache-input-stream.h soup-filter-input-stream.h \
 	soup-cookie-jar-sqlite.h soup-requester.h soup-tld-private.h \
 	soup-misc-private.h soup-proxy-uri-resolver.h \
-	soup-proxy-resolver-wrapper.h
+	soup-proxy-resolver-wrapper.h soup-proxy-uri-resolver.h \
+	soup-cache-private.h
 
 # Images to copy into HTML directory.
 HTML_IMAGES = 
diff --git a/docs/reference/client-howto.xml b/docs/reference/client-howto.xml
index d4d0f37b..e694cb72 100644
--- a/docs/reference/client-howto.xml
+++ b/docs/reference/client-howto.xml
@@ -122,7 +122,7 @@ you can specify various additional options:
 
 <para>
 Other properties are also available; see the <link
-linked="SoupSession"><type>SoupSession</type></link> documentation for
+linkend="SoupSession"><type>SoupSession</type></link> documentation for
 more details.
 </para>
 
diff --git a/docs/reference/libsoup-2.4-sections.txt b/docs/reference/libsoup-2.4-sections.txt
index ca423328..03d35d4b 100644
--- a/docs/reference/libsoup-2.4-sections.txt
+++ b/docs/reference/libsoup-2.4-sections.txt
@@ -51,8 +51,10 @@ SOUP_MESSAGE_SERVER_SIDE
 SOUP_MESSAGE_FIRST_PARTY
 SOUP_MESSAGE_PRIORITY
 SOUP_MESSAGE_REQUEST_BODY
+SOUP_MESSAGE_REQUEST_BODY_DATA
 SOUP_MESSAGE_REQUEST_HEADERS
 SOUP_MESSAGE_RESPONSE_BODY
+SOUP_MESSAGE_RESPONSE_BODY_DATA
 SOUP_MESSAGE_RESPONSE_HEADERS
 SOUP_MESSAGE_TLS_CERTIFICATE
 SOUP_MESSAGE_TLS_ERRORS
@@ -248,6 +250,8 @@ SOUP_SERVER_TLS_CERTIFICATE
 SOUP_SERVER_ASYNC_CONTEXT
 SOUP_SERVER_RAW_PATHS
 SOUP_SERVER_SERVER_HEADER
+SOUP_SERVER_HTTP_ALIASES
+SOUP_SERVER_HTTPS_ALIASES
 <SUBSECTION Standard>
 SOUP_SERVER
 SOUP_IS_SERVER
@@ -439,11 +443,12 @@ SOUP_SESSION_PROXY_URI
 SOUP_SESSION_PROXY_RESOLVER
 SOUP_SESSION_MAX_CONNS
 SOUP_SESSION_MAX_CONNS_PER_HOST
-SOUP_SESSION_USE_NTLM
-SOUP_SESSION_SSL_CA_FILE
-SOUP_SESSION_SSL_USE_SYSTEM_CA_FILE
 SOUP_SESSION_TLS_DATABASE
+SOUP_SESSION_SSL_USE_SYSTEM_CA_FILE
+SOUP_SESSION_SSL_CA_FILE
+SOUP_SESSION_SSL_STRICT
 SOUP_SESSION_ASYNC_CONTEXT
+SOUP_SESSION_USE_THREAD_CONTEXT
 SOUP_SESSION_TIMEOUT
 SOUP_SESSION_IDLE_TIMEOUT
 SOUP_SESSION_USER_AGENT
@@ -452,10 +457,9 @@ SOUP_SESSION_ADD_FEATURE_BY_TYPE
 SOUP_SESSION_REMOVE_FEATURE_BY_TYPE
 SOUP_SESSION_ACCEPT_LANGUAGE
 SOUP_SESSION_ACCEPT_LANGUAGE_AUTO
-SOUP_SESSION_SSL_STRICT
 SOUP_SESSION_HTTP_ALIASES
 SOUP_SESSION_HTTPS_ALIASES
-SOUP_SESSION_USE_THREAD_CONTEXT
+SOUP_SESSION_LOCAL_ADDRESS
 <SUBSECTION Standard>
 SOUP_IS_SESSION
 SOUP_IS_SESSION_CLASS
@@ -471,6 +475,7 @@ SoupConnection
 SoupConnectionState
 SoupMessageQueue
 SoupMessageQueueItem
+SOUP_SESSION_USE_NTLM
 </SECTION>
 
 <SECTION>
@@ -1061,11 +1066,7 @@ SOUP_CACHE_GET_CLASS
 SoupCacheClass
 SoupCachePrivate
 <SUBSECTION Private>
-soup_cache_generate_conditional_request
-soup_cache_get_cacheability
 soup_cache_get_type
-soup_cache_has_response
-soup_cache_send_response
 SoupCacheResponse
 SoupCacheability
 </SECTION>
@@ -1217,6 +1218,7 @@ SOUP_VERSION_2_38
 SOUP_VERSION_2_40
 SOUP_VERSION_2_42
 SOUP_VERSION_2_44
+SOUP_VERSION_2_46
 <SUBSECTION Private>
 SOUP_AVAILABLE_IN_2_24
 SOUP_AVAILABLE_IN_2_26
@@ -1229,6 +1231,7 @@ SOUP_AVAILABLE_IN_2_38
 SOUP_AVAILABLE_IN_2_40
 SOUP_AVAILABLE_IN_2_42
 SOUP_AVAILABLE_IN_2_44
+SOUP_AVAILABLE_IN_2_46
 SOUP_DEPRECATED_IN_2_24
 SOUP_DEPRECATED_IN_2_24_FOR
 SOUP_DEPRECATED_IN_2_26
@@ -1251,6 +1254,8 @@ SOUP_DEPRECATED_IN_2_42
 SOUP_DEPRECATED_IN_2_42_FOR
 SOUP_DEPRECATED_IN_2_44
 SOUP_DEPRECATED_IN_2_44_FOR
+SOUP_DEPRECATED_IN_2_46
+SOUP_DEPRECATED_IN_2_46_FOR
 SOUP_ENCODE_VERSION
 SOUP_VERSION_CUR_STABLE
 SOUP_VERSION_PREV_STABLE
diff --git a/docs/reference/server-howto.xml b/docs/reference/server-howto.xml
index 76c19182..05fb0c05 100644
--- a/docs/reference/server-howto.xml
+++ b/docs/reference/server-howto.xml
@@ -100,7 +100,7 @@ to set a callback to handle certain URI paths.
 
 <informalexample><programlisting>
 	soup_server_add_handler (server, "/foo", server_callback,
-				 data, destroy_notify);
+	                         data, destroy_notify);
 </programlisting></informalexample>
 
 <para>
@@ -131,11 +131,11 @@ A handler callback looks something like this:
 <informalexample><programlisting>
 static void
 server_callback (SoupServer        *server,
-		 SoupMessage       *msg, 
-		 const char        *path,
-		 GHashTable        *query,
-		 SoupClientContext *client,
-		 gpointer           user_data)
+                 SoupMessage       *msg, 
+                 const char        *path,
+                 GHashTable        *query,
+                 SoupClientContext *client,
+                 gpointer           user_data)
 {
 	...
 }
@@ -192,11 +192,11 @@ data available at once.
 <informalexample><programlisting>
 static void
 server_callback (SoupServer        *server,
-		 SoupMessage       *msg, 
-		 const char        *path,
-		 GHashTable        *query,
-		 SoupClientContext *client,
-		 gpointer           user_data)
+                 SoupMessage       *msg, 
+                 const char        *path,
+                 GHashTable        *query,
+                 SoupClientContext *client,
+                 gpointer           user_data)
 {
 	MyServerData *server_data = user_data;
 	const char *mime_type;
@@ -219,7 +219,7 @@ server_callback (SoupServer        *server,
 
 	soup_message_set_status (msg, SOUP_STATUS_OK);
 	soup_message_set_response (msg, mime_type, SOUP_MEMORY_COPY,
-				   body->data, body->len);
+	                           body->data, body->len);
 }
 </programlisting></informalexample>
 
@@ -264,7 +264,7 @@ is emitted indicating that the previous one was written successfully.)
 
 <para>
 The <emphasis role="bold"><literal>simple-proxy</literal></emphasis>
-example in the <literal>tests/</literal> directory gives an example of
+example in the <literal>examples/</literal> directory gives an example of
 using <literal>chunked</literal> encoding.
 </para>
 
@@ -308,8 +308,8 @@ passed to the <literal>server_callback</literal>:
 <informalexample><programlisting>
 static gboolean
 auth_callback (SoupAuthDomain *domain, SoupMessage *msg,
-	       const char *username, const char *password,
-	       gpointer user_data)
+               const char *username, const char *password,
+               gpointer user_data)
 {
 	MyServerData *server_data = user_data;
 	MyUserData *user;
@@ -360,8 +360,8 @@ domains.
 <para>
 If you want to require authentication for some requests under a
 certain path, but not all of them (eg, you want to authenticate
-<literal>PUT</literal>s, but not <literal>GET</literal>s), use a 
-<link
+<literal>PUT</literal> requests, but not <literal>GET</literal>
+requests), use a <link
 linkend="SoupAuthDomainFilter"><type>SoupAuthDomainFilter</type></link>.
 </para>
 
diff --git a/libsoup/soup-content-sniffer.c b/libsoup/soup-content-sniffer.c
index e8f69d47..fb2aa090 100644
--- a/libsoup/soup-content-sniffer.c
+++ b/libsoup/soup-content-sniffer.c
@@ -19,7 +19,7 @@
 
 /**
  * SECTION:soup-content-sniffer
- * @short_description: Content sniffing for #SoupSession
+ * @short_description: Content sniffing for SoupSession
  *
  * A #SoupContentSniffer tries to detect the actual content type of
  * the files that are being downloaded by looking at some of the data
diff --git a/libsoup/soup-cookie-jar.c b/libsoup/soup-cookie-jar.c
index 93fd157b..83229705 100644
--- a/libsoup/soup-cookie-jar.c
+++ b/libsoup/soup-cookie-jar.c
@@ -16,7 +16,7 @@
 
 /**
  * SECTION:soup-cookie-jar
- * @short_description: Automatic cookie handling for #SoupSession
+ * @short_description: Automatic cookie handling for SoupSession
  *
  * A #SoupCookieJar stores #SoupCookie<!-- -->s and arrange for them
  * to be sent with the appropriate #SoupMessage<!-- -->s.
diff --git a/libsoup/soup-cookie.c b/libsoup/soup-cookie.c
index 3f7dcc38..de5efa13 100755
--- a/libsoup/soup-cookie.c
+++ b/libsoup/soup-cookie.c
@@ -18,17 +18,10 @@
 /**
  * SECTION:soup-cookie
  * @short_description: HTTP Cookies
- * @see_also: #SoupMessage
- *
- * #SoupCookie implements HTTP cookies, primarily as described by
- * <ulink
- * url="http://wp.netscape.com/newsref/std/cookie_spec.html">the
- * original Netscape cookie specification</ulink>, but with slight
- * modifications based on <ulink
- * url="http://www.ietf.org/rfc/rfc2109.txt">RFC 2109</ulink>, <ulink
- * url="http://msdn2.microsoft.com/en-us/library/ms533046.aspx">Microsoft's
- * HttpOnly extension attribute</ulink>, and observed real-world usage
- * (and, in particular, based on what Firefox does).
+ * @see_also: #SoupMessage, #SoupCookieJar
+ *
+ * #SoupCookie implements HTTP cookies, as described by <ulink
+ * url="http://tools.ietf.org/html/rfc6265.txt">RFC 6265</ulink>.
  *
  * To have a #SoupSession handle cookies for your appliction
  * automatically, use a #SoupCookieJar.
@@ -58,10 +51,9 @@
  * is a hostname and must match exactly.
  *
  * @expires will be non-%NULL if the cookie uses either the original
- * "expires" attribute, or the "max-age" attribute specified in RFC
- * 2109. If @expires is %NULL, it indicates that neither "expires" nor
- * "max-age" was specified, and the cookie expires at the end of the
- * session.
+ * "expires" attribute, or the newer "max-age" attribute. If @expires
+ * is %NULL, it indicates that neither "expires" nor "max-age" was
+ * specified, and the cookie expires at the end of the session.
  * 
  * If @http_only is set, the cookie should not be exposed to untrusted
  * code (eg, javascript), so as to minimize the danger posed by
diff --git a/libsoup/soup-message-headers.c b/libsoup/soup-message-headers.c
index 28ecaeda..9c704b49 100644
--- a/libsoup/soup-message-headers.c
+++ b/libsoup/soup-message-headers.c
@@ -1159,7 +1159,7 @@ soup_message_headers_get_content_range (SoupMessageHeaders  *hdrs,
  * <note><para>
  * #SoupServer has built-in handling for range requests, and you do
  * not normally need to call this function youself. See
- * soup_message_headers_get_range() for more details.
+ * soup_message_headers_get_ranges() for more details.
  * </para></note>
  *
  * Since: 2.26
diff --git a/libsoup/soup-message.c b/libsoup/soup-message.c
index 07967fc2..23fd8b08 100644
--- a/libsoup/soup-message.c
+++ b/libsoup/soup-message.c
@@ -1780,10 +1780,8 @@ soup_message_set_chunk_allocator (SoupMessage *msg,
  * This disables the actions of #SoupSessionFeature<!-- -->s with the
  * given @feature_type (or a subclass of that type) on @msg, so that
  * @msg is processed as though the feature(s) hadn't been added to the
- * session. Eg, passing #SOUP_TYPE_PROXY_URI_RESOLVER for @feature_type
- * will disable proxy handling and cause @msg to be sent directly to
- * the indicated origin server, regardless of system proxy
- * configuration.
+ * session. Eg, passing #SOUP_TYPE_CONTENT_SNIFFER for @feature_type
+ * will disable Content-Type sniffing on the message.
  *
  * You must call this before queueing @msg on a session; calling it on
  * a message that has already been queued is undefined. In particular,
diff --git a/libsoup/soup-proxy-resolver-default.c b/libsoup/soup-proxy-resolver-default.c
index 9149feef..7fd09349 100644
--- a/libsoup/soup-proxy-resolver-default.c
+++ b/libsoup/soup-proxy-resolver-default.c
@@ -19,16 +19,19 @@
  * SECTION:soup-proxy-resolver-default
  * @short_description: System proxy configuration integration
  *
- * #SoupProxyResolverDefault is a #SoupProxyURIResolver implementation
- * that uses the default gio GProxyResolver to resolve proxies.
+ * #SoupProxyResolverDefault is a <type>SoupProxyURIResolver</type>
+ * implementation that uses the default gio #GProxyResolver to resolve
+ * proxies.
  *
- * Deprecated: In libsoup 2.44 and later, you can set the
+ * In libsoup 2.44 and later, you can set the session's
  * #SoupSession:proxy-resolver property to the resolver returned by
  * g_proxy_resolver_get_default() to get the same effect. Note that
  * for "plain" #SoupSessions (ie, not #SoupSessionAsync or
  * #SoupSessionSync), this is done for you automatically.
  *
  * Since: 2.34
+ *
+ * Deprecated: Use #SoupSession:proxy-resolver
  */
 
 static void soup_proxy_resolver_default_interface_init (SoupProxyURIResolverInterface *proxy_resolver_interface);
diff --git a/libsoup/soup-proxy-uri-resolver.c b/libsoup/soup-proxy-uri-resolver.c
index f075a0f7..7971fcb7 100644
--- a/libsoup/soup-proxy-uri-resolver.c
+++ b/libsoup/soup-proxy-uri-resolver.c
@@ -15,7 +15,7 @@
 #include "soup-proxy-uri-resolver.h"
 #include "soup.h"
 
-/**
+/*
  * SECTION:soup-proxy-uri-resolver
  * @short_description: Interface for locating HTTP proxies
  *
@@ -40,7 +40,7 @@ soup_proxy_uri_resolver_default_init (SoupProxyURIResolverInterface *iface)
 {
 }
 
-/**
+/*
  * SoupProxyURIResolverCallback:
  * @resolver: the #SoupProxyURIResolver
  * @status: a #SoupStatus
@@ -48,9 +48,9 @@ soup_proxy_uri_resolver_default_init (SoupProxyURIResolverInterface *iface)
  * @user_data: data passed to soup_proxy_uri_resolver_get_proxy_uri_async()
  *
  * Callback for soup_proxy_uri_resolver_get_proxy_uri_async()
- **/
+ */
 
-/**
+/*
  * soup_proxy_uri_resolver_get_proxy_uri_async:
  * @proxy_uri_resolver: the #SoupProxyURIResolver
  * @uri: the #SoupURI you want a proxy for
@@ -66,7 +66,7 @@ soup_proxy_uri_resolver_default_init (SoupProxyURIResolverInterface *iface)
  *
  * Deprecated: #SoupProxyURIResolver is deprecated in favor of
  * #GProxyResolver
- **/
+ */
 void
 soup_proxy_uri_resolver_get_proxy_uri_async (SoupProxyURIResolver  *proxy_uri_resolver,
 					     SoupURI               *uri,
@@ -81,7 +81,7 @@ soup_proxy_uri_resolver_get_proxy_uri_async (SoupProxyURIResolver  *proxy_uri_re
 				     callback, user_data);
 }
 
-/**
+/*
  * soup_proxy_uri_resolver_get_proxy_uri_sync:
  * @proxy_uri_resolver: the #SoupProxyURIResolver
  * @uri: the #SoupURI you want a proxy for
@@ -99,7 +99,7 @@ soup_proxy_uri_resolver_get_proxy_uri_async (SoupProxyURIResolver  *proxy_uri_re
  *
  * Deprecated: #SoupProxyURIResolver is deprecated in favor of
  * #GProxyResolver
- **/
+ */
 guint
 soup_proxy_uri_resolver_get_proxy_uri_sync (SoupProxyURIResolver  *proxy_uri_resolver,
 					    SoupURI               *uri,
diff --git a/libsoup/soup-session.c b/libsoup/soup-session.c
index f2e643f3..b3081f14 100644
--- a/libsoup/soup-session.c
+++ b/libsoup/soup-session.c
@@ -3099,9 +3099,9 @@ soup_session_class_init (SoupSessionClass *session_class)
 	 * A proxy to use for all http and https requests in this
 	 * session. Setting this will clear the
 	 * #SoupSession:proxy-resolver property, and remove any
-	 * #SoupProxyURIResolver features that have been added to the
-	 * session. Setting this property will also cancel all
-	 * currently pending messages.
+	 * <type>SoupProxyURIResolver</type> features that have been
+	 * added to the session. Setting this property will also
+	 * cancel all currently pending messages.
 	 *
 	 * Note that #SoupSession will normally handle looking up the
 	 * user's proxy settings for you; you should only use
@@ -3131,8 +3131,8 @@ soup_session_class_init (SoupSessionClass *session_class)
 	 *
 	 * A #GProxyResolver to use with this session. Setting this
 	 * will clear the #SoupSession:proxy-uri property, and remove
-	 * any #SoupProxyURIResolver features that have been added to
-	 * the session.
+	 * any <type>SoupProxyURIResolver</type> features that have
+	 * been added to the session.
 	 *
 	 * By default, in a plain #SoupSession, this is set to the
 	 * default #GProxyResolver, but you can set it to %NULL if you
diff --git a/libsoup/soup-version.c b/libsoup/soup-version.c
index 8a0fa929..31e7262d 100644
--- a/libsoup/soup-version.c
+++ b/libsoup/soup-version.c
@@ -286,3 +286,22 @@ soup_check_version (guint major,
  * Since: 2.42
  */
 
+/**
+ * SOUP_VERSION_2_44:
+ *
+ * A macro that evaluates to the 2.44 version of libsoup, in a format
+ * that can be used by %SOUP_VERSION_MIN_REQUIRED and
+ * %SOUP_VERSION_MAX_ALLOWED.
+ *
+ * Since: 2.44
+ */
+
+/**
+ * SOUP_VERSION_2_46:
+ *
+ * A macro that evaluates to the 2.46 version of libsoup, in a format
+ * that can be used by %SOUP_VERSION_MIN_REQUIRED and
+ * %SOUP_VERSION_MAX_ALLOWED.
+ *
+ * Since: 2.46
+ */