docs: Lots of minor fixes and additions

22 files changed, 315 insertions, 49 deletions

diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index 2e2a8af6..9dbadb30 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=--deprecated-guards=LIBSOUP_DISABLE_DEPRECATED --rebuild-types
+SCAN_OPTIONS=--rebuild-types
 
 # Extra options to supply to gtkdoc-scangobj.
 SCANGOBJ_OPTIONS=
@@ -41,7 +41,9 @@ IGNORE_HFILES= soup.h soup-marshal.h soup-enum-types.h \
 	soup-body-input-stream.h soup-body-output-stream.h \
 	soup-client-input-stream.h soup-content-processor.h \
 	soup-content-sniffer-stream.h soup-io-stream.h \
-	soup-filter-input-stream.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
 
 # Images to copy into HTML directory.
 HTML_IMAGES = 
diff --git a/docs/reference/client-howto.xml b/docs/reference/client-howto.xml
index a53f2ac3..3cf5a4e1 100644
--- a/docs/reference/client-howto.xml
+++ b/docs/reference/client-howto.xml
@@ -164,22 +164,15 @@ functions. Some of the features available in
 	    track of cookies between sessions.
 	</para></listitem>
     </varlistentry>
-</variablelist>
-
-<para>
-And in <application>libsoup-gnome</application>:
-</para>
-
-<variablelist>
     <varlistentry>
-	<term><link linkend="SOUP-TYPE-PROXY-RESOLVER-GNOME:CAPS"><type>SoupProxyResolverGNOME</type></link></term>
+	<term><link linkend="SoupProxyResolverDefault"><type>SoupProxyResolverDefault</type></link></term>
 	<listitem><para>
 	    A feature that automatically determines the correct HTTP
 	    proxy to use for requests.
 	</para></listitem>
     </varlistentry>
     <varlistentry>
-	<term><link linkend="SoupCookieJarSqlite"><type>SoupCookieJarSqlite</type></link></term>
+	<term><link linkend="SoupCookieJarDB"><type>SoupCookieJarDB</type></link></term>
 	<listitem><para>
 	    Support for HTTP cookies stored in an
 	    <application>SQLite</application> database.
@@ -190,7 +183,7 @@ And in <application>libsoup-gnome</application>:
 <para>
 Use the "add_feature_by_type" property/function to add features that
 don't require any configuration (such as <link
-linkend="SOUP-TYPE-PROXY-RESOLVER-GNOME:CAPS"><type>SoupProxyResolverGNOME</type></link>),
+linkend="SoupProxyResolverDefault"><type>SoupProxyResolverDefault</type></link>),
 and the "add_feature" property/function to add features that must be
 constructed first (such as <link
 linkend="SoupLogger"><type>SoupLogger</type></link>). For example, an
@@ -200,7 +193,7 @@ application might do something like the following:
 <informalexample><programlisting>
 	session = soup_session_async_new_with_options (
 #ifdef HAVE_LIBSOUP_GNOME
-		SOUP_SESSION_ADD_FEATURE_BY_TYPE, SOUP_TYPE_PROXY_RESOLVER_GNOME,
+		SOUP_SESSION_ADD_FEATURE_BY_TYPE, SOUP_TYPE_PROXY_RESOLVER_DEFAULT,
 #endif
 		NULL);
 	if (debug_level) {
diff --git a/docs/reference/libsoup-2.4-sections.txt b/docs/reference/libsoup-2.4-sections.txt
index b2952fd0..23f55c0f 100644
--- a/docs/reference/libsoup-2.4-sections.txt
+++ b/docs/reference/libsoup-2.4-sections.txt
@@ -371,6 +371,7 @@ SOUP_ADDRESS_NAME
 SOUP_ADDRESS_PHYSICAL
 SOUP_ADDRESS_PORT
 SOUP_ADDRESS_SOCKADDR
+SOUP_ADDRESS_PROTOCOL
 <SUBSECTION Standard>
 SOUP_ADDRESS
 SOUP_IS_ADDRESS
@@ -583,6 +584,7 @@ soup_socket_is_connected
 <SUBSECTION>
 soup_socket_get_local_address
 soup_socket_get_remote_address
+soup_socket_get_fd
 <SUBSECTION>
 SoupSocketIOStatus
 soup_socket_read
@@ -611,12 +613,6 @@ SOUP_SOCKET_CLASS
 SOUP_IS_SOCKET_CLASS
 SOUP_SOCKET_GET_CLASS
 SoupSocketClass
-<SUBSECTION Private>
-soup_socket_get_fd
-soup_socket_handshake_async
-soup_socket_handshake_sync
-soup_socket_get_gsocket
-soup_socket_get_iostream
 </SECTION>
 
 <SECTION>
@@ -669,8 +665,6 @@ soup_uri_get_fragment
 <SUBSECTION Standard>
 SOUP_TYPE_URI
 soup_uri_get_type
-<SUBSECTION Private>
-uri_decoded_copy
 </SECTION>
 
 <SECTION>
@@ -718,8 +712,6 @@ soup_add_completion
 soup_add_idle
 soup_add_io_watch
 soup_add_timeout
-<SUBSECTION>
-soup_ssl_supported
 <SUBSECTION Private>
 soup_date_copy
 SOUP_TYPE_DATE
@@ -734,6 +726,7 @@ SOUP_CHAR_HTTP_SEPARATOR
 SOUP_CHAR_URI_GEN_DELIMS
 SOUP_CHAR_URI_PERCENT_ENCODED
 SOUP_CHAR_URI_SUB_DELIMS
+soup_ssl_supported
 </SECTION>
 
 <SECTION>
@@ -950,8 +943,14 @@ soup_multipart_input_stream_next_part
 soup_multipart_input_stream_next_part_async
 soup_multipart_input_stream_next_part_finish
 <SUBSECTION Standard>
+SOUP_IS_MULTIPART_INPUT_STREAM
+SOUP_IS_MULTIPART_INPUT_STREAM_CLASS
+SOUP_MULTIPART_INPUT_STREAM
+SOUP_MULTIPART_INPUT_STREAM_CLASS
+SOUP_MULTIPART_INPUT_STREAM_GET_CLASS
 SOUP_TYPE_MULTIPART_INPUT_STREAM
 soup_multipart_input_stream_get_type
+SoupMultipartInputStreamPrivate
 </SECTION>
 
 <SECTION>
@@ -1014,6 +1013,7 @@ soup_proxy_uri_resolver_get_type
 SoupContentSniffer
 soup_content_sniffer_new
 soup_content_sniffer_sniff
+soup_content_sniffer_get_buffer_size
 <SUBSECTION Standard>
 SOUP_CONTENT_SNIFFER
 SOUP_CONTENT_SNIFFER_CLASS
@@ -1213,4 +1213,38 @@ SOUP_VERSION_2_36
 SOUP_VERSION_2_38
 SOUP_VERSION_2_40
 SOUP_VERSION_2_42
+<SUBSECTION Private>
+SOUP_AVAILABLE_IN_2_24
+SOUP_AVAILABLE_IN_2_26
+SOUP_AVAILABLE_IN_2_28
+SOUP_AVAILABLE_IN_2_30
+SOUP_AVAILABLE_IN_2_32
+SOUP_AVAILABLE_IN_2_34
+SOUP_AVAILABLE_IN_2_36
+SOUP_AVAILABLE_IN_2_38
+SOUP_AVAILABLE_IN_2_40
+SOUP_AVAILABLE_IN_2_42
+SOUP_DEPRECATED_IN_2_24
+SOUP_DEPRECATED_IN_2_24_FOR
+SOUP_DEPRECATED_IN_2_26
+SOUP_DEPRECATED_IN_2_26_FOR
+SOUP_DEPRECATED_IN_2_28
+SOUP_DEPRECATED_IN_2_28_FOR
+SOUP_DEPRECATED_IN_2_30
+SOUP_DEPRECATED_IN_2_30_FOR
+SOUP_DEPRECATED_IN_2_32
+SOUP_DEPRECATED_IN_2_32_FOR
+SOUP_DEPRECATED_IN_2_34
+SOUP_DEPRECATED_IN_2_34_FOR
+SOUP_DEPRECATED_IN_2_36
+SOUP_DEPRECATED_IN_2_36_FOR
+SOUP_DEPRECATED_IN_2_38
+SOUP_DEPRECATED_IN_2_38_FOR
+SOUP_DEPRECATED_IN_2_40
+SOUP_DEPRECATED_IN_2_40_FOR
+SOUP_DEPRECATED_IN_2_42
+SOUP_DEPRECATED_IN_2_42_FOR
+SOUP_ENCODE_VERSION
+SOUP_VERSION_CUR_STABLE
+SOUP_VERSION_PREV_STABLE
 </SECTION>
diff --git a/libsoup/soup-address.c b/libsoup/soup-address.c
index 82beb1ea..e1696fb0 100644
--- a/libsoup/soup-address.c
+++ b/libsoup/soup-address.c
@@ -22,6 +22,10 @@
  * #SoupAddress represents the address of a TCP connection endpoint:
  * both the IP address and the port. (It is somewhat like an
  * object-oriented version of struct sockaddr.)
+ *
+ * Although #SoupAddress is still used in some libsoup API's, it
+ * should not be used in new code; use GLib's #GNetworkAddress or
+ * #GSocketAddress instead.
  **/
 
 enum {
diff --git a/libsoup/soup-auth-basic.c b/libsoup/soup-auth-basic.c
index fb491c71..fefe1c7e 100644
--- a/libsoup/soup-auth-basic.c
+++ b/libsoup/soup-auth-basic.c
@@ -19,6 +19,17 @@ typedef struct {
 } SoupAuthBasicPrivate;
 #define SOUP_AUTH_BASIC_GET_PRIVATE(o) (G_TYPE_INSTANCE_GET_PRIVATE ((o), SOUP_TYPE_AUTH_BASIC, SoupAuthBasicPrivate))
 
+/**
+ * SOUP_TYPE_AUTH_BASIC:
+ *
+ * A #GType corresponding to HTTP "Basic" authentication.
+ * #SoupSessions support this by default; if you want to disable
+ * support for it, call soup_session_remove_feature_by_type(),
+ * passing %SOUP_TYPE_AUTH_BASIC.
+ *
+ * Since: 2.34
+ */
+
 G_DEFINE_TYPE (SoupAuthBasic, soup_auth_basic, SOUP_TYPE_AUTH)
 
 static void
diff --git a/libsoup/soup-auth-digest.c b/libsoup/soup-auth-digest.c
index 97ef5616..b95a996f 100644
--- a/libsoup/soup-auth-digest.c
+++ b/libsoup/soup-auth-digest.c
@@ -40,6 +40,17 @@ typedef struct {
 
 static void recompute_hex_a1 (SoupAuthDigestPrivate *priv);
 
+/**
+ * SOUP_TYPE_AUTH_DIGEST:
+ *
+ * A #GType corresponding to HTTP "Digest" authentication.
+ * #SoupSessions support this by default; if you want to disable
+ * support for it, call soup_session_remove_feature_by_type(),
+ * passing %SOUP_TYPE_AUTH_DIGEST.
+ *
+ * Since: 2.34
+ */
+
 G_DEFINE_TYPE (SoupAuthDigest, soup_auth_digest, SOUP_TYPE_AUTH)
 
 static void
diff --git a/libsoup/soup-auth-ntlm.c b/libsoup/soup-auth-ntlm.c
index 391c1c28..dc24d51f 100644
--- a/libsoup/soup-auth-ntlm.c
+++ b/libsoup/soup-auth-ntlm.c
@@ -19,6 +19,17 @@ typedef struct {
 } SoupAuthNTLMPrivate;
 #define SOUP_AUTH_NTLM_GET_PRIVATE(o) (G_TYPE_INSTANCE_GET_PRIVATE ((o), SOUP_TYPE_AUTH_NTLM, SoupAuthNTLMPrivate))
 
+/**
+ * SOUP_TYPE_AUTH_NTLM:
+ *
+ * A #GType corresponding to HTTP-based NTLM authentication.
+ * #SoupSessions do not support this type by default; if you want to
+ * enable support for it, call soup_session_add_feature_by_type(),
+ * passing %SOUP_TYPE_AUTH_NTLM.
+ *
+ * Since: 2.34
+ */
+
 G_DEFINE_TYPE (SoupAuthNTLM, soup_auth_ntlm, SOUP_TYPE_AUTH)
 
 static void
diff --git a/libsoup/soup-cache.c b/libsoup/soup-cache.c
index 7130c5ce..6df16655 100644
--- a/libsoup/soup-cache.c
+++ b/libsoup/soup-cache.c
@@ -1238,6 +1238,9 @@ force_flush_timeout (gpointer data)
  * committed to disk. For doing so it will iterate the #GMainContext
  * associated with @cache's session as long as needed.
  *
+ * Contrast with soup_cache_dump(), which writes out the cache index
+ * file.
+ *
  * Since: 2.34
  */
 void
@@ -1402,6 +1405,19 @@ pack_entry (gpointer data,
 	g_variant_builder_close (entries_builder); /* SOUP_CACHE_PHEADERS_FORMAT */
 }
 
+/**
+ * soup_cache_dump:
+ * @cache: a #SoupCache
+ *
+ * Synchronously writes the cache index out to disk. Contrast with
+ * soup_cache_flush(), which writes pending cache
+ * <emphasis>entries</emphasis> to disk.
+ *
+ * You must call this before exiting if you want your cache data to
+ * persist between sessions.
+ *
+ * Since: 2.34.
+ */
 void
 soup_cache_dump (SoupCache *cache)
 {
@@ -1430,6 +1446,14 @@ soup_cache_dump (SoupCache *cache)
 	g_variant_unref (cache_variant);
 }
 
+/**
+ * soup_cache_load:
+ * @cache: a #SoupCache
+ *
+ * Loads the contents of @cache's index into memory.
+ *
+ * Since: 2.34
+ */
 void
 soup_cache_load (SoupCache *cache)
 {
@@ -1507,6 +1531,15 @@ soup_cache_load (SoupCache *cache)
 	g_variant_unref (cache_variant);
 }
 
+/**
+ * soup_cache_set_max_size:
+ * @cache: a #SoupCache
+ * @max_size: the maximum size of the cache, in bytes
+ *
+ * Sets the maximum size of the cache.
+ *
+ * Since: 2.34
+ */
 void
 soup_cache_set_max_size (SoupCache *cache,
 			 guint      max_size)
@@ -1515,6 +1548,16 @@ soup_cache_set_max_size (SoupCache *cache,
 	cache->priv->max_entry_data_size = cache->priv->max_size / MAX_ENTRY_DATA_PERCENTAGE;
 }
 
+/**
+ * soup_cache_get_max_size:
+ * @cache: a #SoupCache
+ *
+ * Gets the maximum size of the cache.
+ *
+ * Return value: the maximum size of the cache, in bytes.
+ *
+ * Since: 2.34
+ */
 guint
 soup_cache_get_max_size (SoupCache *cache)
 {
diff --git a/libsoup/soup-cookie-jar.c b/libsoup/soup-cookie-jar.c
index 80bb8327..38ddf923 100644
--- a/libsoup/soup-cookie-jar.c
+++ b/libsoup/soup-cookie-jar.c
@@ -795,6 +795,9 @@ soup_cookie_jar_delete_cookie (SoupCookieJar *jar,
  * document. If no first party is set in a message when this policy is
  * in effect, cookies will be assumed to be third party by default.
  *
+ * The policy for accepting or rejecting cookies returned in
+ * responses.
+ *
  * Since: 2.30
  */
 
diff --git a/libsoup/soup-date.c b/libsoup/soup-date.c
index 16988f41..d3dcf6f4 100644
--- a/libsoup/soup-date.c
+++ b/libsoup/soup-date.c
@@ -188,7 +188,7 @@ soup_date_new (int year, int month, int day,
  * offset_seconds is 0, returns the current time.
  *
  * If @offset_seconds would indicate a time not expressible as a
- * #time_t, the return value will be clamped into range.
+ * <type>time_t</type>, the return value will be clamped into range.
  *
  * Return value: a new #SoupDate
  **/
@@ -525,7 +525,7 @@ soup_date_new_from_string (const char *date_string)
 
 /**
  * soup_date_new_from_time_t:
- * @when: a #time_t
+ * @when: a <type>time_t</type>
  *
  * Creates a #SoupDate corresponding to @when
  *
@@ -680,13 +680,13 @@ soup_date_to_string (SoupDate *date, SoupDateFormat format)
  * soup_date_to_time_t:
  * @date: a #SoupDate
  *
- * Converts @date to a %time_t.
+ * Converts @date to a <type>time_t</type>.
  *
- * If @date is not representable as a %time_t, it will be clamped into
- * range. (In particular, some HTTP cookies have expiration dates
- * after "Y2.038k" (2038-01-19T03:14:07Z).)
+ * If @date is not representable as a <type>time_t</type>, it will be
+ * clamped into range. (In particular, some HTTP cookies have
+ * expiration dates after "Y2.038k" (2038-01-19T03:14:07Z).)
  *
- * Return value: @date as a %time_t
+ * Return value: @date as a <type>time_t</type>
  **/
 time_t
 soup_date_to_time_t (SoupDate *date)
diff --git a/libsoup/soup-logger.c b/libsoup/soup-logger.c
index a9f49bfb..52d74cda 100644
--- a/libsoup/soup-logger.c
+++ b/libsoup/soup-logger.c
@@ -52,7 +52,7 @@
  * </screen></informalexample>
  *
  * The <literal>Soup-Debug-Timestamp</literal> line gives the time (as
- * a #time_t) when the request was sent, or the response fully
+ * a <type>time_t</type>) when the request was sent, or the response fully
  * received.
  *
  * The <literal>Soup-Debug</literal> line gives further debugging
diff --git a/libsoup/soup-message-body.c b/libsoup/soup-message-body.c
index c541887f..dfc29fae 100644
--- a/libsoup/soup-message-body.c
+++ b/libsoup/soup-message-body.c
@@ -313,6 +313,10 @@ soup_buffer_free (SoupBuffer *buffer)
  * soup_buffer_get_as_bytes:
  * @buffer: a #SoupBuffer
  *
+ * Creates a #GBytes pointing to the same memory as @buffer. The
+ * #GBytes will hold a reference on @buffer to ensure that it is not
+ * freed while the #GBytes is still valid.
+ *
  * Returns: (transfer full): a new #GBytes which has the same content
  * as the #SoupBuffer.
  *
diff --git a/libsoup/soup-message.c b/libsoup/soup-message.c
index 6c62b27d..badcd166 100644
--- a/libsoup/soup-message.c
+++ b/libsoup/soup-message.c
@@ -1623,12 +1623,13 @@ soup_message_set_status_full (SoupMessage *msg,
  * destroyed
  *
  * Sets an alternate chunk-allocation function to use when reading
- * @msg's body when using the traditional (ie, non-#SoupRequest-based)
- * API. Every time data is available to read, libsoup will call
- * @allocator, which should return a #SoupBuffer. (See
- * #SoupChunkAllocator for additional details.) Libsoup will then read
- * data from the network into that buffer, and update the buffer's
- * <literal>length</literal> to indicate how much data it read.
+ * @msg's body when using the traditional (ie,
+ * non-#SoupRequest<!-- -->-based) API. Every time data is available
+ * to read, libsoup will call @allocator, which should return a
+ * #SoupBuffer. (See #SoupChunkAllocator for additional details.)
+ * Libsoup will then read data from the network into that buffer, and
+ * update the buffer's <literal>length</literal> to indicate how much
+ * data it read.
  *
  * Generally, a custom chunk allocator would be used in conjunction
  * with soup_message_body_set_accumulate() %FALSE and
diff --git a/libsoup/soup-multipart-input-stream.c b/libsoup/soup-multipart-input-stream.c
index 9cd1b3af..dee4e59f 100644
--- a/libsoup/soup-multipart-input-stream.c
+++ b/libsoup/soup-multipart-input-stream.c
@@ -508,14 +508,12 @@ soup_multipart_input_stream_next_part_thread (GTask        *task,
  * @io_priority: the I/O priority for the request.
  * @cancellable: a #GCancellable.
  * @callback: callback to call when request is satisfied.
+ * @data: data for @callback
  *
  * Obtains a #GInputStream for the next request. See
  * soup_multipart_input_stream_next_part() for details on the
  * workflow.
  *
- * Return value: a new #GInputStream, or %NULL if there are no more
- * parts
- *
  * Since: 2.40
  */
 void
diff --git a/libsoup/soup-multipart-input-stream.h b/libsoup/soup-multipart-input-stream.h
index 20cdefdf..8b735063 100644
--- a/libsoup/soup-multipart-input-stream.h
+++ b/libsoup/soup-multipart-input-stream.h
@@ -54,7 +54,7 @@ void                      soup_multipart_input_stream_next_part_async  (SoupMult
 
 SOUP_AVAILABLE_IN_2_40
 GInputStream             *soup_multipart_input_stream_next_part_finish (SoupMultipartInputStream  *multipart,
-									GAsyncResult              *res,
+									GAsyncResult              *result,
 									GError                   **error);
 
 SOUP_AVAILABLE_IN_2_40
diff --git a/libsoup/soup-request-http.c b/libsoup/soup-request-http.c
index 15e087a8..871ca0ea 100644
--- a/libsoup/soup-request-http.c
+++ b/libsoup/soup-request-http.c
@@ -34,6 +34,25 @@
 
 G_DEFINE_TYPE (SoupRequestHTTP, soup_request_http, SOUP_TYPE_REQUEST)
 
+/**
+ * SoupRequestHTTP:
+ * @method: the HTTP method
+ * @request_uri: the request URI
+ * @request_version: the HTTP version of the request
+ * @request_headers: the request headers
+ * @status_code: the HTTP status code
+ * @reason_phrase: the status phrase associated with @status_code
+ * @response_version: the HTTP version of the response
+ * @response_headers: the response headers
+ *
+ * Represents an HTTP message being sent or received via the
+ * #SoupRequest API. The fields on this object reflect the values on
+ * the request's underlying #SoupMessage; see the #SoupMessage
+ * documentation for more information.
+ *
+ * Since: 2.42
+ */
+
 enum {
 	PROP_0,
 
@@ -575,6 +594,15 @@ soup_request_http_get_message (SoupRequestHTTP *http)
 	return g_object_ref (http->priv->msg);
 }
 
+/**
+ * soup_request_http_set_method:
+ * @http: a #SoupRequestHTTP
+ * @method: the HTTP method
+ *
+ * Sets @http to use @method as its request method.
+ *
+ * Since: 2.42
+ */
 void
 soup_request_http_set_method (SoupRequestHTTP *http,
 			      const char      *method)
diff --git a/libsoup/soup-request.c b/libsoup/soup-request.c
index 5fd4a02a..02d0ca47 100644
--- a/libsoup/soup-request.c
+++ b/libsoup/soup-request.c
@@ -282,6 +282,20 @@ soup_request_class_init (SoupRequestClass *request_class)
 	object_class->set_property = soup_request_set_property;
 	object_class->get_property = soup_request_get_property;
 
+	/**
+	 * SOUP_REQUEST_URI:
+	 *
+	 * Alias for the #SoupRequest:uri property, qv.
+	 *
+	 * Since: 2.42
+	 */
+	/**
+	 * SoupRequest:uri:
+	 *
+	 * The request URI.
+	 *
+	 * Since: 2.42
+	 */
 	g_object_class_install_property (
 		 object_class, PROP_URI,
 		 g_param_spec_boxed (SOUP_REQUEST_URI,
@@ -289,6 +303,20 @@ soup_request_class_init (SoupRequestClass *request_class)
 				     "The request URI",
 				     SOUP_TYPE_URI,
 				     G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
+	/**
+	 * SOUP_REQUEST_SESSION:
+	 *
+	 * Alias for the #SoupRequest:session property, qv.
+	 *
+	 * Since: 2.42
+	 */
+	/**
+	 * SoupRequest:session:
+	 *
+	 * The request's #SoupSession.
+	 *
+	 * Since: 2.42
+	 */
 	g_object_class_install_property (
 		 object_class, PROP_SESSION,
 		 g_param_spec_object (SOUP_REQUEST_SESSION,
diff --git a/libsoup/soup-session.c b/libsoup/soup-session.c
index cfcadb27..43e5f6be 100644
--- a/libsoup/soup-session.c
+++ b/libsoup/soup-session.c
@@ -2956,7 +2956,7 @@ soup_session_class_init (SoupSessionClass *session_class)
 				     NULL,
 				     G_PARAM_READWRITE | G_PARAM_DEPRECATED));
 	/**
-	 * SOUP_SESSION_USE_SYSTEM_CA_FILE:
+	 * SOUP_SESSION_SSL_USE_SYSTEM_CA_FILE:
 	 *
 	 * Alias for the #SoupSession:ssl-use-system-ca-file property,
 	 * qv.
@@ -3027,8 +3027,8 @@ soup_session_class_init (SoupSessionClass *session_class)
 	/**
 	 * SoupSession:ssl-strict:
 	 *
-	 * Normally, if #SoupSession:tlsdb is set (including if it was
-	 * set via #SoupSession:ssl-use-system-ca-file or
+	 * 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
 	 * certificate that is invalid (ie, expired) or that is not
 	 * signed by one of the given CA certificates, and the
@@ -4010,7 +4010,7 @@ soup_session_request_http_uri (SoupSession  *session,
 /**
  * SOUP_REQUEST_ERROR:
  *
- * A #GError domain for #SoupRequest-related errors. Used with
+ * A #GError domain for #SoupRequest<!-- -->-related errors. Used with
  * #SoupRequestError.
  *
  * Since: 2.42
diff --git a/libsoup/soup-socket.c b/libsoup/soup-socket.c
index cd4bf761..6b485bab 100644
--- a/libsoup/soup-socket.c
+++ b/libsoup/soup-socket.c
@@ -836,6 +836,17 @@ soup_socket_connect_sync (SoupSocket *sock, GCancellable *cancellable)
 	return socket_connected (sock, conn, error);
 }
 
+/**
+ * soup_socket_get_fd:
+ * @sock: a #SoupSocket
+ *
+ * Gets @sock's underlying file descriptor.
+ *
+ * Note that fiddling with the file descriptor may break the
+ * #SoupSocket.
+ *
+ * Return value: @sock's file descriptor.
+ */
 int
 soup_socket_get_fd (SoupSocket *sock)
 {
diff --git a/libsoup/soup-tld.c b/libsoup/soup-tld.c
index 5fdb44a0..c6faed13 100644
--- a/libsoup/soup-tld.c
+++ b/libsoup/soup-tld.c
@@ -17,6 +17,15 @@
 #include "soup.h"
 #include "soup-tld-private.h"
 
+/**
+ * SECTION:soup-tld
+ * @short_description: Top-Level Domain Utilities
+ *
+ * These functions can be used to parse hostnames to attempt to determine
+ * what part of the name belongs to the domain owner, and what part is
+ * simply a "public suffix" such as ".com".
+ */
+
 static void soup_tld_ensure_rules_hash_table (void);
 static const char *soup_tld_get_base_domain_internal (const char *hostname,
 						      guint       additional_domains,
@@ -27,8 +36,7 @@ static SoupTLDEntry tld_entries[] = {
 #include "tld_data.inc"
 };
 
-/**
- * Stores the entries data in a hash table to ease and speed up
+/* Stores the entries data in a hash table to ease and speed up
  * searches.
  */
 static void
@@ -49,7 +57,6 @@ soup_tld_ensure_rules_hash_table (void)
 
 /**
  * soup_tld_get_base_domain:
- * @tld: a #SoupTLD
  * @hostname: a UTF-8 hostname in its canonical representation form
  * @error: return location for a #GError, or %NULL to ignore
  *   errors. See #SoupTLDError for the available error codes
@@ -83,7 +90,6 @@ soup_tld_get_base_domain (const char *hostname, GError **error)
 
 /**
  * soup_tld_domain_is_public_suffix:
- * @tld: a #SoupTLD
  * @domain: a UTF-8 domain in its canonical representation form
  *
  * Looks whether the @domain passed as argument is a public domain
@@ -131,6 +137,31 @@ soup_tld_domain_is_public_suffix (const char *domain)
 	return TRUE;
 }
 
+/**
+ * SOUP_TLD_ERROR:
+ *
+ * The #GError domain for soup-tld-related errors.
+ *
+ * Since: 2.40
+ */
+/**
+ * SoupTLDError:
+ * @SOUP_TLD_ERROR_INVALID_HOSTNAME: A hostname was syntactically
+ *   invalid.
+ * @SOUP_TLD_ERROR_IS_IP_ADDRESS: The passed-in "hostname" was
+ *   actually an IP address (and thus has no base domain or
+ *   public suffix).
+ * @SOUP_TLD_ERROR_NOT_ENOUGH_DOMAINS: The passed-in hostname
+ *   did not have enough components. Eg, calling
+ *   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.
+ *
+ * Error codes for %SOUP_TLD_ERROR.
+ *
+ * Since: 2.40
+ */
+
 GQuark
 soup_tld_error_quark (void)
 {
diff --git a/libsoup/soup-uri.c b/libsoup/soup-uri.c
index c1d5720f..28b3025c 100644
--- a/libsoup/soup-uri.c
+++ b/libsoup/soup-uri.c
@@ -105,6 +105,57 @@
  * Since: 2.24
  **/
 
+/**
+ * SOUP_URI_SCHEME_HTTP:
+ *
+ * "http" as an interned string; you can compare this directly to a
+ * #SoupURI's <literal>scheme</literal> field using
+ * <literal>==</literal>.
+ */
+/**
+ * SOUP_URI_SCHEME_HTTPS:
+ *
+ * "https" as an interned string; you can compare this directly to a
+ * #SoupURI's <literal>scheme</literal> field using
+ * <literal>==</literal>.
+ */
+/**
+ * SOUP_URI_SCHEME_FTP:
+ *
+ * "ftp" as an interned string; you can compare this directly to a
+ * #SoupURI's <literal>scheme</literal> field using
+ * <literal>==</literal>.
+ *
+ * Since: 2.30
+ */
+/**
+ * SOUP_URI_SCHEME_FILE:
+ *
+ * "file" as an interned string; you can compare this directly to a
+ * #SoupURI's <literal>scheme</literal> field using
+ * <literal>==</literal>.
+ *
+ * Since: 2.30
+ */
+/**
+ * SOUP_URI_SCHEME_DATA:
+ *
+ * "data" as an interned string; you can compare this directly to a
+ * #SoupURI's <literal>scheme</literal> field using
+ * <literal>==</literal>.
+ *
+ * Since: 2.30
+ */
+/**
+ * SOUP_URI_SCHEME_RESOURCE:
+ *
+ * "data" as an interned string; you can compare this directly to a
+ * #SoupURI's <literal>scheme</literal> field using
+ * <literal>==</literal>.
+ *
+ * Since: 2.42
+ */
+
 static void append_uri_encoded (GString *str, const char *in, const char *extra_enc_chars);
 static char *uri_normalized_copy (const char *str, int length, const char *unescape_extra);
 
diff --git a/libsoup/soup-version.c b/libsoup/soup-version.c
index 84c146eb..8a0fa929 100644
--- a/libsoup/soup-version.c
+++ b/libsoup/soup-version.c
@@ -52,6 +52,8 @@
  * @minor: minor version (e.g. 42 for version 2.42.0)
  * @micro: micro version (e.g. 0 for version 2.42.0)
  *
+ * Macro to test the version of libsoup being compiled against.
+ *
  * Returns: %TRUE if the version of the libsoup header files
  * is the same as or newer than the passed-in version.
  *