docs: Mass docs fixups

28 files changed, 160 insertions, 213 deletions

diff --git a/docs/reference/client-howto.xml b/docs/reference/client-howto.xml
index cdaf6d48..0eb78b55 100644
--- a/docs/reference/client-howto.xml
+++ b/docs/reference/client-howto.xml
@@ -91,7 +91,7 @@ you can specify various additional options:
 	</para></listitem>
     </varlistentry>
     <varlistentry>
-	<term><link linkend="SOUP-SESSION-PROXY-RESOLVER:CAPS"><literal>SOUP_SESSION_PROXY_RESOLVER</literal></link> and <link linkend="SOUP-SESSION-PROXY-URI:CAPS"><literal>SOUP_SESSION_PROXY_URI</literal></link></term>
+	<term><link linkend="SOUP-SESSION-PROXY-RESOLVER:CAPS"><literal>SOUP_SESSION_PROXY_RESOLVER</literal></link></term>
 	<listitem>
 	    <para>
 		<link linkend="SOUP-SESSION-PROXY-RESOLVER:CAPS"><literal>SOUP_SESSION_PROXY_RESOLVER</literal></link>
@@ -102,11 +102,6 @@ you can specify various additional options:
 		linkend="g-proxy-resolver-get-default"><function>g_proxy_resolver_get_default</function></link>,
 		so you do not need to set it yourself.
 	    </para>
-	    <para>
-		Alternatively, if you want all requests to go through a
-		single proxy, you can set <link
-		linkend="SOUP-SESSION-PROXY-URI:CAPS"><literal>SOUP_SESSION_PROXY_URI</literal></link>.
-	    </para>
 	</listitem>
     </varlistentry>
     <varlistentry>
diff --git a/docs/reference/libsoup-3.0-docs.xml b/docs/reference/libsoup-3.0-docs.xml
index 0d415bab..79bf610d 100644
--- a/docs/reference/libsoup-3.0-docs.xml
+++ b/docs/reference/libsoup-3.0-docs.xml
@@ -49,18 +49,28 @@
     <xi:include href="xml/soup-auth-manager.xml"/>
     <xi:include href="xml/soup-content-decoder.xml"/>
     <xi:include href="xml/soup-content-sniffer.xml"/>
-    <xi:include href="xml/soup-cookie-jar.xml"/>
-    <xi:include href="xml/soup-cookie-jar-text.xml"/>
-    <xi:include href="xml/soup-cookie-jar-db.xml"/>
-    <xi:include href="xml/soup-hsts-enforcer.xml"/>
-    <xi:include href="xml/soup-hsts-enforcer-db.xml"/>
     <xi:include href="xml/soup-logger.xml"/>
+    <section>
+        <title>Cookie Support</title>
+        <xi:include href="xml/soup-cookie-jar.xml"/>
+        <xi:include href="xml/soup-cookie-jar-text.xml"/>
+        <xi:include href="xml/soup-cookie-jar-db.xml"/>
+    </section>
+    <section>
+        <title>HSTS Support</title>
+        <xi:include href="xml/soup-hsts-enforcer.xml"/>
+        <xi:include href="xml/soup-hsts-enforcer-db.xml"/>
+    </section>
   </chapter>
 
   <chapter>
     <title>Web Services APIs</title>
     <xi:include href="xml/soup-form.xml"/>
-    <xi:include href="xml/soup-websocket.xml"/>
+    <section>
+        <title>WebSocket Support</title>
+        <xi:include href="xml/soup-websocket.xml"/>
+        <xi:include href="xml/soup-websocket-extension.xml"/>
+    </section>
   </chapter>
 
   <index id="api-index-full">
diff --git a/docs/reference/libsoup-3.0-sections.txt b/docs/reference/libsoup-3.0-sections.txt
index 5a608fd3..e9a8631e 100644
--- a/docs/reference/libsoup-3.0-sections.txt
+++ b/docs/reference/libsoup-3.0-sections.txt
@@ -61,6 +61,8 @@ SOUP_MESSAGE_RESPONSE_BODY_DATA
 SOUP_MESSAGE_RESPONSE_HEADERS
 SOUP_MESSAGE_TLS_CERTIFICATE
 SOUP_MESSAGE_TLS_ERRORS
+SOUP_MESSAGE_IS_TOP_LEVEL_NAVIGATION
+SOUP_MESSAGE_SITE_FOR_COOKIES
 <SUBSECTION Standard>
 SOUP_MESSAGE
 SOUP_IS_MESSAGE
@@ -243,6 +245,8 @@ soup_client_context_get_auth_domain
 soup_client_context_get_auth_user
 soup_client_context_get_socket
 soup_client_context_steal_connection
+<SUBSECTION Private>
+soup_client_context_get_soup_socket
 <SUBSECTION>
 soup_server_add_auth_domain
 soup_server_remove_auth_domain
@@ -397,9 +401,6 @@ soup_session_get_features
 soup_session_get_feature
 soup_session_get_feature_for_message
 soup_session_has_feature
-SoupSessionConnectProgressCallback
-soup_session_connect_async
-soup_session_connect_finish
 <SUBSECTION>
 SOUP_SESSION_PROXY_RESOLVER
 SOUP_SESSION_MAX_CONNS
@@ -430,8 +431,11 @@ SoupSessionClass
 soup_session_get_type
 soup_request_error_quark
 <SUBSECTION Private>
+SoupSocket
 SoupConnection
 SoupConnectionState
+SOUP_TYPE_CONNECTION_STATE
+soup_connection_state_get_type
 SoupMessageQueue
 SoupMessageQueueItem
 SOUP_SESSION_USE_NTLM
@@ -491,6 +495,11 @@ SOUP_AUTH_REALM
 SOUP_AUTH_HOST
 SOUP_AUTH_IS_FOR_PROXY
 SOUP_AUTH_IS_AUTHENTICATED
+<SUBSECTION Private>
+SoupAuthBasic
+SoupAuthDigest
+SoupAuthNTLM
+SoupAuthNegotiate
 <SUBSECTION Standard>
 SOUP_AUTH
 SOUP_IS_AUTH
@@ -584,6 +593,8 @@ soup_uri_get_type
 SoupDateFormat
 soup_date_time_new_from_http_string
 soup_date_time_to_string
+<SUBSECTION Private>
+soup_date_time_is_past
 <SUBSECTION>
 soup_headers_parse_request
 soup_headers_parse_response
@@ -601,26 +612,6 @@ soup_header_parse_semi_param_list_strict
 soup_header_free_param_list
 soup_header_g_string_append_param
 soup_header_g_string_append_param_quoted
-<SUBSECTION>
-soup_str_case_equal
-soup_str_case_hash
-<SUBSECTION>
-soup_add_completion
-soup_add_idle
-soup_add_io_watch
-soup_add_timeout
-<SUBSECTION Private>
-soup_char_is_token
-soup_char_is_uri_gen_delims
-soup_char_is_uri_percent_encoded
-soup_char_is_uri_sub_delims
-soup_char_is_uri_unreserved
-SOUP_CHAR_HTTP_CTL
-SOUP_CHAR_HTTP_SEPARATOR
-SOUP_CHAR_URI_GEN_DELIMS
-SOUP_CHAR_URI_PERCENT_ENCODED
-SOUP_CHAR_URI_SUB_DELIMS
-soup_ssl_supported
 </SECTION>
 
 <SECTION>
@@ -654,6 +645,9 @@ soup_logger_set_response_filter
 <SUBSECTION>
 SoupLoggerPrinter
 soup_logger_set_printer
+<SUBSECTION>
+SOUP_LOGGER_LEVEL
+SOUP_LOGGER_MAX_BODY_SIZE
 <SUBSECTION Standard>
 SoupLoggerClass
 soup_logger_get_type
@@ -755,7 +749,6 @@ soup_cookie_jar_get_type
 
 <SECTION>
 <FILE>soup-multipart</FILE>
-<TITLE>SoupMultipart</TITLE>
 SoupMultipart
 soup_multipart_new
 soup_multipart_new_from_message
@@ -1011,7 +1004,16 @@ SOUP_VERSION_2_46
 SOUP_VERSION_2_48
 SOUP_VERSION_2_50
 SOUP_VERSION_2_52
+SOUP_VERSION_2_54
+SOUP_VERSION_2_56
+SOUP_VERSION_2_58
+SOUP_VERSION_2_62
+SOUP_VERSION_2_66
+SOUP_VERSION_2_68
+SOUP_VERSION_2_70
+SOUP_VERSION_2_72
 <SUBSECTION Private>
+SOUP_AVAILABLE_IN_2_4
 SOUP_AVAILABLE_IN_2_24
 SOUP_AVAILABLE_IN_2_26
 SOUP_AVAILABLE_IN_2_28
@@ -1027,6 +1029,14 @@ SOUP_AVAILABLE_IN_2_46
 SOUP_AVAILABLE_IN_2_48
 SOUP_AVAILABLE_IN_2_50
 SOUP_AVAILABLE_IN_2_52
+SOUP_AVAILABLE_IN_2_54
+SOUP_AVAILABLE_IN_2_56
+SOUP_AVAILABLE_IN_2_58
+SOUP_AVAILABLE_IN_2_62
+SOUP_AVAILABLE_IN_2_66
+SOUP_AVAILABLE_IN_2_68
+SOUP_AVAILABLE_IN_2_70
+SOUP_AVAILABLE_IN_2_72
 SOUP_DEPRECATED_IN_2_24
 SOUP_DEPRECATED_IN_2_24_FOR
 SOUP_DEPRECATED_IN_2_26
@@ -1057,7 +1067,20 @@ SOUP_DEPRECATED_IN_2_50
 SOUP_DEPRECATED_IN_2_50_FOR
 SOUP_DEPRECATED_IN_2_52
 SOUP_DEPRECATED_IN_2_52_FOR
+SOUP_DEPRECATED_IN_2_54
+SOUP_DEPRECATED_IN_2_54_FOR
+SOUP_DEPRECATED_IN_2_56
+SOUP_DEPRECATED_IN_2_56_FOR
+SOUP_DEPRECATED_IN_2_58
+SOUP_DEPRECATED_IN_2_58_FOR
+SOUP_DEPRECATED_IN_2_62
+SOUP_DEPRECATED_IN_2_62_FOR
+SOUP_DEPRECATED_IN_2_66
+SOUP_DEPRECATED_IN_2_66_FOR
+SOUP_DEPRECATED_IN_2_70
+SOUP_DEPRECATED_IN_2_70_FOR
 SOUP_ENCODE_VERSION
+SOUP_VAR
 SOUP_VERSION_CUR_STABLE
 SOUP_VERSION_PREV_STABLE
 </SECTION>
@@ -1065,7 +1088,6 @@ SOUP_VERSION_PREV_STABLE
 <SECTION>
 <FILE>soup-websocket</FILE>
 <TITLE>WebSockets</TITLE>
-<SUBSECTION>
 soup_websocket_client_prepare_handshake
 soup_websocket_client_prepare_handshake_with_extensions
 soup_websocket_client_verify_handshake
@@ -1086,6 +1108,10 @@ soup_websocket_connection_get_uri
 soup_websocket_connection_get_origin
 soup_websocket_connection_get_protocol
 soup_websocket_connection_get_extensions
+soup_websocket_connection_get_max_incoming_payload_size
+soup_websocket_connection_set_max_incoming_payload_size
+soup_websocket_connection_get_keepalive_interval
+soup_websocket_connection_set_keepalive_interval
 SoupWebsocketState
 soup_websocket_connection_get_state
 SoupWebsocketDataType
@@ -1097,36 +1123,45 @@ soup_websocket_connection_close
 soup_websocket_connection_get_close_code
 soup_websocket_connection_get_close_data
 <SUBSECTION>
-SoupWebsocketExtensionManager
-<SUBSECTION>
-SoupWebsocketExtension
-SoupWebsocketExtensionDeflate
-soup_websocket_extension_configure
-soup_websocket_extension_get_request_params
-soup_websocket_extension_get_response_params
-soup_websocket_extension_process_outgoing_message
-soup_websocket_extension_process_incoming_message
-<SUBSECTION>
 SoupWebsocketError
 SOUP_WEBSOCKET_ERROR
-<SUBSECTION Private>
+<SUBSECTION Standard>
 SoupWebsocketConnectionClass
 SoupWebsocketConnectionPrivate
-SoupWebsocketExtensionManagerClass
-SoupWebsocketExtensionClass
-SoupWebsocketExtensionDeflateClass
 SOUP_IS_WEBSOCKET_CONNECTION
 SOUP_IS_WEBSOCKET_CONNECTION_CLASS
 SOUP_TYPE_WEBSOCKET_CONNECTION
 SOUP_WEBSOCKET_CONNECTION
 SOUP_WEBSOCKET_CONNECTION_CLASS
 SOUP_WEBSOCKET_CONNECTION_GET_CLASS
-SOUP_IS_WEBSOCKET_EXTENSION_MANAGER
-SOUP_IS_WEBSOCKET_EXTENSION_MANAGER_CLASS
+soup_websocket_close_code_get_type
+soup_websocket_connection_get_type
+soup_websocket_connection_type_get_type
+soup_websocket_data_type_get_type
+soup_websocket_error_get_quark
+soup_websocket_error_get_type
+soup_websocket_state_get_type
+</SECTION>
+
+<SECTION>
+<FILE>soup-websocket-extension</FILE>
+<TITLE>WebSocket Extensions</TITLE>
+SoupWebsocketExtension
+soup_websocket_extension_configure
+soup_websocket_extension_get_request_params
+soup_websocket_extension_get_response_params
+soup_websocket_extension_process_outgoing_message
+soup_websocket_extension_process_incoming_message
+<SUBSECTION>
+SoupWebsocketExtensionClass
+<SUBSECTION>
+SoupWebsocketExtensionDeflate
+SOUP_TYPE_WEBSOCKET_EXTENSION_DEFLATE
+<SUBSECTION>
+SoupWebsocketExtensionManager
 SOUP_TYPE_WEBSOCKET_EXTENSION_MANAGER
-SOUP_WEBSOCKET_EXTENSION_MANAGER
-SOUP_WEBSOCKET_EXTENSION_MANAGER_CLASS
-SOUP_WEBSOCKET_EXTENSION_MANAGER_GET_CLASS
+<SUBSECTION Standard>
+soup_websocket_extension_get_type
 SOUP_IS_WEBSOCKET_EXTENSION
 SOUP_IS_WEBSOCKET_EXTENSION_CLASS
 SOUP_TYPE_WEBSOCKET_EXTENSION
@@ -1135,20 +1170,18 @@ SOUP_WEBSOCKET_EXTENSION_CLASS
 SOUP_WEBSOCKET_EXTENSION_GET_CLASS
 SOUP_IS_WEBSOCKET_EXTENSION_DEFLATE
 SOUP_IS_WEBSOCKET_EXTENSION_DEFLATE_CLASS
-SOUP_TYPE_WEBSOCKET_EXTENSION_DEFLATE
 SOUP_WEBSOCKET_EXTENSION_DEFLATE
 SOUP_WEBSOCKET_EXTENSION_DEFLATE_CLASS
 SOUP_WEBSOCKET_EXTENSION_DEFLATE_GET_CLASS
-soup_websocket_close_code_get_type
-soup_websocket_connection_get_type
-soup_websocket_connection_type_get_type
-soup_websocket_extension_manager_get_type
-soup_websocket_extension_get_type
 soup_websocket_extension_deflate_get_type
-soup_websocket_data_type_get_type
-soup_websocket_error_get_quark
-soup_websocket_error_get_type
-soup_websocket_state_get_type
+SoupWebsocketExtensionDeflateClass
+SoupWebsocketExtensionManagerClass
+soup_websocket_extension_manager_get_type
+SOUP_IS_WEBSOCKET_EXTENSION_MANAGER
+SOUP_IS_WEBSOCKET_EXTENSION_MANAGER_CLASS
+SOUP_WEBSOCKET_EXTENSION_MANAGER
+SOUP_WEBSOCKET_EXTENSION_MANAGER_CLASS
+SOUP_WEBSOCKET_EXTENSION_MANAGER_GET_CLASS
 </SECTION>
 
 <SECTION>
@@ -1164,28 +1197,33 @@ soup_hsts_enforcer_set_session_policy
 soup_hsts_enforcer_get_domains
 soup_hsts_enforcer_get_policies
 <SUBSECTION>
+SOUP_HSTS_ENFORCER_DB_FILENAME
+<SUBSECTION Standard>
+SOUP_HSTS_ENFORCER
+SOUP_HSTS_ENFORCER_CLASS
+SOUP_HSTS_ENFORCER_GET_CLASS
+SOUP_TYPE_HSTS_ENFORCER
+SOUP_IS_HSTS_ENFORCER
+SOUP_IS_HSTS_ENFORCER_CLASS
+soup_hsts_enforcer_get_type
+</SECTION>
+
+<SECTION>
+<FILE>soup-hsts-policy</FILE>
 SoupHSTSPolicy
 soup_hsts_policy_new
 soup_hsts_policy_new_full
-soup_hsts_policy_new_permanent
+soup_hsts_policy_new_session_policy
 soup_hsts_policy_new_from_response
 soup_hsts_policy_copy
 soup_hsts_policy_equal
 soup_hsts_policy_free
-<SUBSECTION>
 soup_hsts_policy_get_domain
 soup_hsts_policy_is_expired
 soup_hsts_policy_includes_subdomains
 soup_hsts_policy_is_session_policy
 SOUP_HSTS_POLICY_MAX_AGE_PAST
 <SUBSECTION Standard>
-SOUP_HSTS_ENFORCER
-SOUP_HSTS_ENFORCER_CLASS
-SOUP_HSTS_ENFORCER_GET_CLASS
-SOUP_TYPE_HSTS_ENFORCER
-SOUP_IS_HSTS_ENFORCER
-SOUP_IS_HSTS_ENFORCER_CLASS
-soup_hsts_enforcer_get_type
 SOUP_TYPE_HSTS_POLICY
 soup_hsts_policy_get_type
 </SECTION>
diff --git a/docs/reference/meson.build b/docs/reference/meson.build
index 6aec3a0a..ba1e84fc 100644
--- a/docs/reference/meson.build
+++ b/docs/reference/meson.build
@@ -1,25 +1,17 @@
 ignore_headers = [
+  'gconstructor.h',
   'soup.h',
   'soup-enum-types.h',
   'soup-message-private.h',
   'soup-session-private.h',
-  'soup-auth-basic.h',
-  'soup-auth-digest.h',
-  'soup-auth-ntlm.h',
-  'soup-auth-negotiate.h',
+  'soup-auth-digest-private.h',
   'soup-brotli-decompressor.h',
   'soup-connection.h',
   'soup-connection-auth.h',
   'soup-message-queue.h',
   'soup-path-map.h',
-  'soup-gnome-features.h',
-  'soup-proxy-resolver.h',
-  'soup-proxy-resolver-gnome.h',
-  'soup-proxy-resolver-static.h',
   'soup-directory-input-stream.h',
   'soup-http-input-stream.h',
-  'soup-password-manager.h',
-  'soup-password-manager-gnome.h',
   'soup-converter-wrapper.h',
   'soup-body-input-stream.h',
   'soup-body-output-stream.h',
@@ -30,16 +22,12 @@ ignore_headers = [
   'soup-cache-input-stream.h',
   'soup-filter-input-stream.h',
   'soup-cookie-jar-sqlite.h',
-  'soup-requester.h',
-  'soup-misc-private.h',
-  'soup-proxy-uri-resolver.h',
-  'soup-proxy-resolver-wrapper.h',
-  'soup-proxy-uri-resolver.h',
   'soup-cache-private.h',
   'soup-cache-client-input-stream.h',
+  'soup-socket.h',
   'soup-socket-private.h',
-  'soup-value-utils.h',
   'soup-websocket-extension-manager-private.h',
+  'soup-misc.h',
 ]
 
 mkdb_args = [
@@ -63,6 +51,7 @@ gnome.gtkdoc('libsoup-3.0',
   mkdb_args : mkdb_args,
   scan_args : scan_args,
   fixxref_args : [
+    '--html-dir=@0@'.format(get_option('datadir') / 'gtk-doc', 'html'),
     '--extra-dir=@0@'.format(glib_docpath / 'glib'),
     '--extra-dir=@0@'.format(glib_docpath /'gobject'),
     '--extra-dir=@0@'.format(glib_docpath /'gio'),
diff --git a/docs/reference/server-howto.xml b/docs/reference/server-howto.xml
index 336a2af4..074909cd 100644
--- a/docs/reference/server-howto.xml
+++ b/docs/reference/server-howto.xml
@@ -114,46 +114,6 @@ a few additional options:
 </para>
 </refsect2>
 
-<refsect2 id="soup-server-old-api">
-<title>The Old SoupServer Listening API</title>
-
-<para>
-<link
-linkend="soup-server-listen"><function>soup_server_listen</function></link>,
-etc, are available only in <application>libsoup</application> 2.46 and
-later. In earlier versions, there was a simpler API, in which a server
-could only listen on a single port, determined at construct time
-either by passing the <link
-linkend="SOUP-SERVER-INTERFACE:CAPS"><literal>SOUP_SERVER_INTERFACE</literal></link>
-property (to specify a <link
-linkend="SoupAddress"><type>SoupAddress</type></link> to listen on),
-or the <link
-linkend="SOUP-SERVER-PORT:CAPS"><literal>SOUP_SERVER_PORT</literal></link>
-property (to specify a port to listen on, on all interfaces). The <link
-linkend="SOUP-SERVER-SSL-CERT-FILE:CAPS"><literal>SOUP_SERVER_SSL_CERT_FILE</literal></link>
-and <link
-linkend="SOUP-SERVER-SSL-KEY-FILE:CAPS"><literal>SOUP_SERVER_SSL_KEY_FILE</literal></link>
-properties could be used to create an HTTP server.
-</para>
-
-<para>
-When using this API, if <link
-linkend="SoupServer"><type>SoupServer</type></link> is unable to bind
-the listening socket, or unable to read the provided certificate or
-key files, then it will return <literal>NULL</literal> from its
-constructor (with no further indication of what exactly went wrong).
-</para>
-
-<para>
-Additionally, when using this API, it is necessary to call <link
-linkend="soup-server-run"><function>soup_server_run</function></link>
-or <link
-linkend="soup-server-run-async"><function>soup_server_run_async</function></link>
-to start the server after creating it.
-</para>
-
-</refsect2>
-
 <refsect2>
 <title>Adding Handlers</title>
 
diff --git a/libsoup/Soup-3.0.metadata b/libsoup/Soup-3.0.metadata
index da138e39..b2e58984 100644
--- a/libsoup/Soup-3.0.metadata
+++ b/libsoup/Soup-3.0.metadata
@@ -35,9 +35,6 @@ URI
 
 // Not enough GIR information
 MessageBody.data type="uint8[]" array_length_field="length"
-Date
-	.new_from_time_t.when type="time_t"
-	.to_time_t type="time_t"
 
 // Simplify memory management
 MessageBody
diff --git a/libsoup/cache/soup-cache.c b/libsoup/cache/soup-cache.c
index ae79d793..5a00467c 100644
--- a/libsoup/cache/soup-cache.c
+++ b/libsoup/cache/soup-cache.c
@@ -1491,7 +1491,7 @@ pack_entry (gpointer data,
  * You must call this before exiting if you want your cache data to
  * persist between sessions.
  *
- * Since: 2.34.
+ * Since: 2.34
  */
 void
 soup_cache_dump (SoupCache *cache)
diff --git a/libsoup/hsts/soup-hsts-enforcer.c b/libsoup/hsts/soup-hsts-enforcer.c
index e3fc2e58..9201f3c6 100644
--- a/libsoup/hsts/soup-hsts-enforcer.c
+++ b/libsoup/hsts/soup-hsts-enforcer.c
@@ -37,7 +37,7 @@
  * SoupMessage:uri in order to be aware of changes in the message URI.
  *
  * Note that #SoupHSTSEnforcer does not support any form of long-term
- * HSTS policy persistence. See #SoupHSTSDBEnforcer for a persistent
+ * HSTS policy persistence. See #SoupHSTSEnforcerDB for a persistent
  * enforcer.
  *
  **/
diff --git a/libsoup/hsts/soup-hsts-enforcer.h b/libsoup/hsts/soup-hsts-enforcer.h
index ba7d43f5..d0223188 100644
--- a/libsoup/hsts/soup-hsts-enforcer.h
+++ b/libsoup/hsts/soup-hsts-enforcer.h
@@ -24,7 +24,8 @@ G_DECLARE_DERIVABLE_TYPE (SoupHSTSEnforcer, soup_hsts_enforcer, SOUP, HSTS_ENFOR
  * change the scheme of the #SoupURI in the #SoupMessage to HTTPS. Implementations might want to
  * chain up to the @has_valid_policy in the parent class to check, for instance, for runtime
  * policies.
- * @changed: the class closure for the #SoupHSTSEnforcer::changed signal.
+ * @changed: The class closure for the #SoupHSTSEnforcer::changed signal.
+ * @hsts_enforced: The class closure for the #SoupHSTSEnforcer::hsts-enforced signal.
  **/
 struct _SoupHSTSEnforcerClass {
 	GObjectClass parent_class;
@@ -40,6 +41,7 @@ struct _SoupHSTSEnforcerClass {
 	void (*hsts_enforced) (SoupHSTSEnforcer *enforcer,
 			       SoupMessage      *message);
 
+        /* <private> */
 	gpointer padding[4];
 };
 
diff --git a/libsoup/hsts/soup-hsts-policy.c b/libsoup/hsts/soup-hsts-policy.c
index 39bce01d..2bae29ba 100644
--- a/libsoup/hsts/soup-hsts-policy.c
+++ b/libsoup/hsts/soup-hsts-policy.c
@@ -19,25 +19,14 @@
 #include "soup.h"
 
 /**
- * SECTION:soup-hsts-policy
- * @short_description: HTTP Strict Transport Security policies
- * @see_also: #SoupHSTSEnforcer
- *
- * #SoupHSTSPolicy implements HTTP policies, as described by <ulink
- * url="http://tools.ietf.org/html/rfc6797">RFC 6797</ulink>.
- *
- * To have a #SoupSession handle HSTS policies for your appliction
- * automatically, use a #SoupHSTSEnforcer.
- **/
-
-/**
  * SoupHSTSPolicy:
  * @domain: The domain or hostname that the policy applies to
  * @max_age: The maximum age, in seconds, that the policy is valid
  * @expires: the policy expiration time, or %NULL for a permanent session policy
  * @include_subdomains: %TRUE if the policy applies on subdomains
  *
- * An HTTP Strict Transport Security policy.
+ * #SoupHSTSPolicy implements HTTP policies, as described by
+ * [RFC 6797](http://tools.ietf.org/html/rfc6797).
  *
  * @domain represents the host that this policy applies to. The domain
  * must be IDNA-canonicalized. soup_hsts_policy_new() and related methods
diff --git a/libsoup/soup-form.c b/libsoup/soup-form.c
index 1de391d1..90449dd7 100644
--- a/libsoup/soup-form.c
+++ b/libsoup/soup-form.c
@@ -20,9 +20,7 @@
  * @see_also: #SoupMultipart
  *
  * libsoup contains several help methods for processing HTML forms as
- * defined by <ulink
- * url="http://www.w3.org/TR/html401/interact/forms.html#h-17.13">the
- * HTML 4.01 specification</ulink>.
+ * defined by the [the HTML 4.01 specification](http://www.w3.org/TR/html401/interact/forms.html#h-17.13).
  **/
 
 /**
diff --git a/libsoup/soup-message-headers.c b/libsoup/soup-message-headers.c
index 166e7be3..0b0abda1 100644
--- a/libsoup/soup-message-headers.c
+++ b/libsoup/soup-message-headers.c
@@ -49,7 +49,7 @@ typedef struct {
 	char *value;
 } SoupHeader;
 
-struct SoupMessageHeaders {
+struct _SoupMessageHeaders {
 	GArray *array;
 	GHashTable *concat;
 	SoupMessageHeadersType type;
diff --git a/libsoup/soup-message-headers.h b/libsoup/soup-message-headers.h
index f69e093a..6498e3da 100644
--- a/libsoup/soup-message-headers.h
+++ b/libsoup/soup-message-headers.h
@@ -9,7 +9,7 @@
 
 G_BEGIN_DECLS
 
-typedef struct SoupMessageHeaders SoupMessageHeaders;
+typedef struct _SoupMessageHeaders SoupMessageHeaders;
 SOUP_AVAILABLE_IN_2_4
 GType soup_message_headers_get_type (void);
 #define SOUP_TYPE_MESSAGE_HEADERS (soup_message_headers_get_type ())
diff --git a/libsoup/soup-multipart.c b/libsoup/soup-multipart.c
index 67df98fa..9ff3e62a 100644
--- a/libsoup/soup-multipart.c
+++ b/libsoup/soup-multipart.c
@@ -40,7 +40,7 @@
  * Since: 2.26
  **/
 
-struct SoupMultipart {
+struct _SoupMultipart {
 	char *mime_type, *boundary;
 	GPtrArray *headers, *bodies;
 };
diff --git a/libsoup/soup-multipart.h b/libsoup/soup-multipart.h
index e5a46c24..9724bdc6 100644
--- a/libsoup/soup-multipart.h
+++ b/libsoup/soup-multipart.h
@@ -11,7 +11,7 @@
 
 G_BEGIN_DECLS
 
-typedef struct SoupMultipart SoupMultipart;
+typedef struct _SoupMultipart SoupMultipart;
 
 SOUP_AVAILABLE_IN_2_26
 GType soup_multipart_get_type (void);
diff --git a/libsoup/soup-request.c b/libsoup/soup-request.c
index 8b04ae5c..6a1f53ba 100644
--- a/libsoup/soup-request.c
+++ b/libsoup/soup-request.c
@@ -205,9 +205,6 @@ soup_request_default_send_finish (SoupRequest          *request,
  * Synchronously requests the URI pointed to by @request, and returns
  * a #GInputStream that can be used to read its contents.
  *
- * Note that you cannot use this method with #SoupRequests attached to
- * a #SoupSessionAsync.
- *
  * Return value: (transfer full): a #GInputStream that can be used to
  *   read from the URI pointed to by @request.
  *
diff --git a/libsoup/soup-server.c b/libsoup/soup-server.c
index 2aa4a7e2..aa5f2203 100644
--- a/libsoup/soup-server.c
+++ b/libsoup/soup-server.c
@@ -103,7 +103,7 @@
  * If you want to process https connections in addition to (or instead
  * of) http connections, you can either set the
  * %SOUP_SERVER_TLS_CERTIFICATE property when creating the server, or
- * else call soup_server_set_ssl_certificate() after creating it.
+ * else call soup_server_set_ssl_cert_file() after creating it.
  *
  * Once the server is set up, make one or more calls to
  * soup_server_listen(), soup_server_listen_local(), or
@@ -129,7 +129,7 @@ enum {
 
 static guint signals[LAST_SIGNAL] = { 0 };
 
-struct SoupClientContext {
+struct _SoupClientContext {
 	SoupServer     *server;
 	SoupSocket     *sock;
 	GSocket        *gsock;
@@ -795,9 +795,6 @@ soup_server_is_https (SoupServer *server)
  * You should treat these sockets as read-only; writing to or
  * modifiying any of these sockets may cause @server to malfunction.
  *
- * (Beware that in contrast to the old soup_server_get_listener(), this
- * function returns #GSockets, not #SoupSockets.)
- *
  * Return value: (transfer container) (element-type Gio.Socket): a
  * list of listening sockets.
  **/
@@ -1232,9 +1229,7 @@ new_connection (SoupSocket *listener, SoupSocket *sock, gpointer user_data)
  * soup_server_disconnect:
  * @server: a #SoupServer
  *
- * Closes and frees @server's listening sockets. If you are using the
- * old #SoupServer APIs, this also includes the effect of
- * soup_server_quit().
+ * Closes and frees @server's listening sockets.
  *
  * Note that if there are currently requests in progress on @server,
  * that they will continue to be processed if @server's #GMainContext
@@ -1890,7 +1885,7 @@ soup_client_context_get_auth_user (SoupClientContext *client)
  * state of the connection; if the response to the current
  * #SoupMessage has not yet finished being sent, then it will be
  * discarded; you can steal the connection from a
- * #SoupMessage:wrote-informational or #SoupMessage:wrote-body signal
+ * #SoupMessage::wrote-informational or #SoupMessage::wrote-body signal
  * handler if you need to wait for part or all of the response to be
  * sent.
  *
@@ -2151,8 +2146,7 @@ soup_server_add_early_handler (SoupServer            *server,
  * only requests containing a compatible "Sec-WebSocket-Protocols"
  * header will be accepted. More complicated requirements can be
  * handled by adding a normal handler to @path, and having it perform
- * whatever checks are needed (possibly calling
- * soup_server_check_websocket_handshake() one or more times), and
+ * whatever checks are needed and
  * setting a failure status code if the handshake should be rejected.
  **/
 void
@@ -2261,7 +2255,7 @@ soup_server_remove_auth_domain (SoupServer *server, SoupAuthDomain *auth_domain)
  * the server handler without having the full response ready yet. Use
  * soup_server_unpause_message() to resume I/O.
  *
- * This must only be called on #SoupMessages which were created by the
+ * This must only be called on a #SoupMessage which was created by the
  * #SoupServer and are currently doing I/O, such as those passed into a
  * #SoupServerCallback or emitted in a #SoupServer::request-read signal.
  **/
@@ -2286,7 +2280,7 @@ soup_server_pause_message (SoupServer *server,
  *
  * I/O won't actually resume until you return to the main loop.
  *
- * This must only be called on #SoupMessages which were created by the
+ * This must only be called on a #SoupMessage which was created by the
  * #SoupServer and are currently doing I/O, such as those passed into a
  * #SoupServerCallback or emitted in a #SoupServer::request-read signal.
  **/
diff --git a/libsoup/soup-server.h b/libsoup/soup-server.h
index 57cd5ce2..eb9a13b7 100644
--- a/libsoup/soup-server.h
+++ b/libsoup/soup-server.h
@@ -15,7 +15,7 @@ G_BEGIN_DECLS
 SOUP_AVAILABLE_IN_2_4
 G_DECLARE_DERIVABLE_TYPE (SoupServer, soup_server, SOUP, SERVER, GObject)
 
-typedef struct SoupClientContext SoupClientContext;
+typedef struct _SoupClientContext SoupClientContext;
 SOUP_AVAILABLE_IN_2_4
 GType soup_client_context_get_type (void);
 #define SOUP_TYPE_CLIENT_CONTEXT (soup_client_context_get_type ())
diff --git a/libsoup/soup-session.c b/libsoup/soup-session.c
index 3fb7e7ab..16fd4db2 100644
--- a/libsoup/soup-session.c
+++ b/libsoup/soup-session.c
@@ -1941,11 +1941,6 @@ soup_session_requeue_message (SoupSession *session, SoupMessage *msg)
  * Unlike with soup_session_queue_message(), @msg is not freed upon
  * return.
  *
- * (Note that if you call this method on a #SoupSessionAsync, it will
- * still use asynchronous I/O internally, running the glib main loop
- * to process the message, which may also cause other events to be
- * processed.)
- *
  * Contrast this method with soup_session_send(), which also
  * synchronously sends a message, but returns before reading the
  * response body, and allows you to read the response via a
@@ -1977,9 +1972,6 @@ soup_session_send_message (SoupSession *session, SoupMessage *msg)
  *
  * Pauses HTTP I/O on @msg. Call soup_session_unpause_message() to
  * resume I/O.
- *
- * This may only be called for asynchronous messages (those sent on a
- * #SoupSessionAsync or using soup_session_queue_message()).
  **/
 void
 soup_session_pause_message (SoupSession *session,
@@ -2055,9 +2047,6 @@ soup_session_kick_queue (SoupSession *session)
  * If @msg is being sent via blocking I/O, this will resume reading or
  * writing immediately. If @msg is using non-blocking I/O, then
  * reading or writing won't resume until you return to the main loop.
- *
- * This may only be called for asynchronous messages (those sent on a
- * #SoupSessionAsync or using soup_session_queue_message()).
  **/
 void
 soup_session_unpause_message (SoupSession *session,
@@ -2106,12 +2095,8 @@ soup_session_unpause_message (SoupSession *session,
  * The response headers, on the other hand, will always be either
  * empty or complete.
  *
- * Beware that with the deprecated #SoupSessionAsync, messages queued
- * with soup_session_queue_message() will have their callbacks invoked
- * before soup_session_cancel_message() returns. The plain
- * #SoupSession does not have this behavior; cancelling an
- * asynchronous message will merely queue its callback to be run after
- * returning to the main loop.
+ * Note that cancelling an asynchronous message will merely queue its
+ * callback to be run after returning to the main loop.
  **/
 void
 soup_session_cancel_message (SoupSession *session, SoupMessage *msg, guint status_code)
@@ -2154,10 +2139,7 @@ soup_session_cancel_message (SoupSession *session, SoupMessage *msg, guint statu
  * persistent connections.
  *
  * The message cancellation has the same semantics as with
- * soup_session_cancel_message(); asynchronous requests on a
- * #SoupSessionAsync will have their callback called before
- * soup_session_abort() returns. Requests on a plain #SoupSession will
- * not.
+ * soup_session_cancel_message().
  **/
 void
 soup_session_abort (SoupSession *session)
@@ -2884,7 +2866,7 @@ soup_session_class_init (SoupSessionClass *session_class)
 	 * Sets the #GTlsDatabase to use for validating SSL/TLS
 	 * certificates.
 	 *
-	 * Note that setting the #SoupSession:ssl-ca-file or
+	 * Note that setting the
 	 * #SoupSession:ssl-use-system-ca-file property will cause
 	 * this property to be set to a #GTlsDatabase corresponding to
 	 * the indicated file or system default.
@@ -2913,8 +2895,8 @@ soup_session_class_init (SoupSessionClass *session_class)
 	 * SoupSession:ssl-strict:
 	 *
 	 * Normally, if #SoupSession:tls-database is set (including if
-	 * it was set via #SoupSession:ssl-use-system-ca-file or
-	 * #SoupSession:ssl-ca-file), then libsoup will reject any
+	 * it was set via #SoupSession:ssl-use-system-ca-file),
+	 * 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
@@ -3799,9 +3781,6 @@ soup_session_send_finish (SoupSession   *session,
  * synchronously sends a #SoupMessage, but doesn't return until the
  * response has been completely read.
  *
- * (Note that this method cannot be called on the deprecated
- * #SoupSessionAsync subclass.)
- *
  * Return value: (transfer full): a #GInputStream for reading the
  *   response body, or %NULL on error.
  *
diff --git a/libsoup/soup-socket.c b/libsoup/soup-socket.c
index b876b6a8..5b0c604c 100644
--- a/libsoup/soup-socket.c
+++ b/libsoup/soup-socket.c
@@ -20,7 +20,7 @@
 #include "soup-filter-input-stream.h"
 #include "soup-io-stream.h"
 
-/**
+/*<private>
  * SECTION:soup-socket
  * @short_description: A network socket
  *
diff --git a/libsoup/soup-status.c b/libsoup/soup-status.c
index fddb2a6e..df608f03 100644
--- a/libsoup/soup-status.c
+++ b/libsoup/soup-status.c
@@ -106,6 +106,7 @@
  * @SOUP_STATUS_USE_PROXY: 305 Use Proxy (HTTP)
  * @SOUP_STATUS_NOT_APPEARING_IN_THIS_PROTOCOL: 306 [Unused] (HTTP)
  * @SOUP_STATUS_TEMPORARY_REDIRECT: 307 Temporary Redirect (HTTP)
+ * @SOUP_STATUS_PERMANENT_REDIRECT: 308 Permanent Redirect (HTTP)
  * @SOUP_STATUS_BAD_REQUEST: 400 Bad Request (HTTP)
  * @SOUP_STATUS_UNAUTHORIZED: 401 Unauthorized (HTTP)
  * @SOUP_STATUS_PAYMENT_REQUIRED: 402 Payment Required (HTTP)
@@ -206,6 +207,7 @@ static const struct {
 	{ SOUP_STATUS_NOT_MODIFIED,               "Not Modified" },
 	{ SOUP_STATUS_USE_PROXY,                  "Use Proxy" },
 	{ SOUP_STATUS_TEMPORARY_REDIRECT,         "Temporary Redirect" },
+        { SOUP_STATUS_PERMANENT_REDIRECT,         "Permanent Redirect" },
 
 	/* Client error */
 	{ SOUP_STATUS_BAD_REQUEST,                "Bad Request" },
diff --git a/libsoup/soup-tld.c b/libsoup/soup-tld.c
index 3455e22d..a1e9bad4 100644
--- a/libsoup/soup-tld.c
+++ b/libsoup/soup-tld.c
@@ -122,6 +122,8 @@ soup_tld_domain_is_public_suffix (const char *domain)
  *   soup_tld_get_base_domain() on <literal>"co.uk"</literal>.
  * @SOUP_TLD_ERROR_NO_BASE_DOMAIN: The passed-in hostname has
  *   no recognized public suffix.
+ * @SOUP_TLD_ERROR_NO_PSL_DATA: The Public Suffix List was not
+ *   available.
  *
  * Error codes for %SOUP_TLD_ERROR.
  *
diff --git a/libsoup/soup-types.h b/libsoup/soup-types.h
index a2127122..abd7ea21 100644
--- a/libsoup/soup-types.h
+++ b/libsoup/soup-types.h
@@ -26,7 +26,6 @@ typedef struct _SoupRequest             SoupRequest;
 typedef struct _SoupRequestHTTP         SoupRequestHTTP;
 typedef struct _SoupServer              SoupServer;
 typedef struct _SoupSession             SoupSession;
-typedef struct _SoupSessionAsync        SoupSessionAsync;
 typedef struct _SoupSessionFeature      SoupSessionFeature;
 typedef struct _SoupSocket              SoupSocket;
 typedef struct _SoupURI                 SoupURI;
diff --git a/libsoup/websocket/soup-websocket-extension-deflate.c b/libsoup/websocket/soup-websocket-extension-deflate.c
index c343f1d0..77e6c1d5 100644
--- a/libsoup/websocket/soup-websocket-extension-deflate.c
+++ b/libsoup/websocket/soup-websocket-extension-deflate.c
@@ -66,11 +66,8 @@ typedef struct {
         Inflater inflater;
 } SoupWebsocketExtensionDeflatePrivate;
 
-/*
- * SECTION:soup-websocket-extension-deflate
- * @title: SoupWebsocketExtensionDeflate
- * @short_description: A permessage-deflate WebSocketExtension
- * @see_also: #SoupWebsocketExtension
+/**
+ * SoupWebsocketExtensionDeflate:
  *
  * A SoupWebsocketExtensionDeflate is a #SoupWebsocketExtension
  * implementing permessage-deflate (RFC 7692).
diff --git a/libsoup/websocket/soup-websocket-extension-manager.c b/libsoup/websocket/soup-websocket-extension-manager.c
index 90ca105d..f213d6d6 100644
--- a/libsoup/websocket/soup-websocket-extension-manager.c
+++ b/libsoup/websocket/soup-websocket-extension-manager.c
@@ -33,10 +33,7 @@
 #include "soup-websocket-extension-manager-private.h"
 
 /**
- * SECTION:soup-websocket-extension-manager
- * @title: SoupWebsocketExtensionManager
- * @short_description: WebSocket extensions manager
- * @see_also: #SoupSession, #SoupWebsocketExtension
+ * SoupWebsocketExtensionManager:
  *
  * SoupWebsocketExtensionManager is the #SoupSessionFeature that handles WebSockets
  * extensions for a #SoupSession.
diff --git a/libsoup/websocket/soup-websocket-extension.c b/libsoup/websocket/soup-websocket-extension.c
index 91ae6951..68d2bbb4 100644
--- a/libsoup/websocket/soup-websocket-extension.c
+++ b/libsoup/websocket/soup-websocket-extension.c
@@ -38,6 +38,7 @@
 
 /**
  * SoupWebsocketExtensionClass:
+ * @name: the name of the extension
  * @parent_class: the parent class
  * @configure: called to configure the extension with the given parameters
  * @get_request_params: called by the client to build the request header.
diff --git a/libsoup/websocket/soup-websocket-extension.h b/libsoup/websocket/soup-websocket-extension.h
index 7d2d3686..7f2cfa1c 100644
--- a/libsoup/websocket/soup-websocket-extension.h
+++ b/libsoup/websocket/soup-websocket-extension.h
@@ -55,6 +55,7 @@ struct _SoupWebsocketExtensionClass {
 					       GBytes                     *payload,
                                                GError                    **error);
 
+        /* <private> */
 	gpointer padding[6];
 };
 
diff --git a/libsoup/websocket/soup-websocket.c b/libsoup/websocket/soup-websocket.c
index 13b56474..45ec0925 100644
--- a/libsoup/websocket/soup-websocket.c
+++ b/libsoup/websocket/soup-websocket.c
@@ -625,7 +625,7 @@ process_extensions (SoupMessage *msg,
  * only requests containing valid supported extensions in
  * "Sec-WebSocket-Extensions" header will be accepted.
  *
- * Normally soup_websocket_server_process_handshake_with_extensioins()
+ * Normally soup_websocket_server_process_handshake_with_extensions()
  * will take care of this for you, and if you use
  * soup_server_add_websocket_handler() to handle accepting WebSocket
  * connections, it will call that for you. However, this function may