docs: Port individual docs to gi-docgen

47 files changed, 1963 insertions, 2149 deletions

diff --git a/libsoup/auth/soup-auth-basic.c b/libsoup/auth/soup-auth-basic.c
index 7a35362c..4ca43872 100644
--- a/libsoup/auth/soup-auth-basic.c
+++ b/libsoup/auth/soup-auth-basic.c
@@ -23,11 +23,12 @@ typedef struct {
 } SoupAuthBasicPrivate;
 
 /**
- * SOUP_TYPE_AUTH_BASIC:
+ * SoupAuthBasic:
  *
- * 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(),
+ * HTTP "Basic" authentication.
+ *
+ * [class@Session]s support this by default; if you want to disable
+ * support for it, call [method@Session.remove_feature_by_type],
  * passing %SOUP_TYPE_AUTH_BASIC.
  *
  */
diff --git a/libsoup/auth/soup-auth-digest.c b/libsoup/auth/soup-auth-digest.c
index 13b6cc16..2e81849a 100644
--- a/libsoup/auth/soup-auth-digest.c
+++ b/libsoup/auth/soup-auth-digest.c
@@ -46,11 +46,12 @@ typedef struct {
 static void recompute_hex_a1 (SoupAuthDigestPrivate *priv);
 
 /**
- * SOUP_TYPE_AUTH_DIGEST:
+ * SoupAuthDigest:
  *
- * 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(),
+ * HTTP "Digest" authentication.
+ *
+ * [class@Session]s support this by default; if you want to disable
+ * support for it, call [method@Session.remove_feature_by_type]
  * passing %SOUP_TYPE_AUTH_DIGEST.
  *
  */
diff --git a/libsoup/auth/soup-auth-manager.c b/libsoup/auth/soup-auth-manager.c
index 47ce2a2d..89b83bb5 100644
--- a/libsoup/auth/soup-auth-manager.c
+++ b/libsoup/auth/soup-auth-manager.c
@@ -22,40 +22,26 @@
 #include "soup-uri-utils-private.h"
 
 /**
- * SECTION:soup-auth-manager
- * @short_description: HTTP client-side authentication handler
- * @see_also: #SoupSession, #SoupAuth
+ * SoupAuthManager:
+ *
+ * HTTP client-side authentication handler.
  *
- * #SoupAuthManager is the #SoupSessionFeature that handles HTTP
- * authentication for a #SoupSession.
+ * #SoupAuthManager is the [iface@SessionFeature] that handles HTTP
+ * authentication for a [class@Session].
  *
  * A #SoupAuthManager is added to the session by default, and normally
  * you don't need to worry about it at all. However, if you want to
  * disable HTTP authentication, you can remove the feature from the
- * session with soup_session_remove_feature_by_type(), or disable it on
- * individual requests with soup_message_disable_feature().
+ * session with [method@Session.remove_feature_by_type] or disable it on
+ * individual requests with [method@Message.disable_feature].
  *
- **/
-
-/**
- * SoupAuthManager:
+ * You can use this with [method@Session.remove_feature_by_type] or
+ * [method@Message.disable_feature].
  *
- * Class for managing client-side HTTP authentication.
- */
-
-/**
- * SOUP_TYPE_AUTH_MANAGER:
- *
- * The #GType of #SoupAuthManager; you can use this with
- * soup_session_remove_feature_by_type() or
- * soup_message_disable_feature().
- *
- * (Although this type has only been publicly visible since libsoup
- * 2.42, it has always existed in the background, and you can use
- * <literal><code>g_type_from_name ("SoupAuthManager")</code></literal>
- * to get its #GType in earlier releases.)
- *
- */
+ * (Although this type has only been publicly visible since libsoup 2.42, it has
+ * always existed in the background, and you can use `g_type_from_name
+ * ("SoupAuthManager")` to get its [alias@GLib.Type] in earlier releases.)
+ **/
 static void soup_auth_manager_session_feature_init (SoupSessionFeatureInterface *feature_interface, gpointer interface_data);
 
 enum {
@@ -137,8 +123,8 @@ soup_auth_manager_class_init (SoupAuthManagerClass *auth_manager_class)
 	 * Emitted when the manager requires the application to
 	 * provide authentication credentials.
 	 *
-	 * #SoupMessage connects to this signal and emits its own
-	 * #SoupMessage::authenticate signal when it is emitted, so
+	 * [class@Message] connects to this signal and emits its own
+	 * [signal@Message::authenticate] signal when it is emitted, so
 	 * you shouldn't need to use this signal directly.
 	 */
 	signals[AUTHENTICATE] =
@@ -827,10 +813,11 @@ soup_auth_manager_request_unqueued (SoupSessionFeature *manager,
  * @auth: the #SoupAuth to use
  *
  * Records that @auth is to be used under @uri, as though a
- * WWW-Authenticate header had been received at that URI. This can be
- * used to "preload" @manager's auth cache, to avoid an extra HTTP
- * round trip in the case where you know ahead of time that a 401
- * response will be returned.
+ * WWW-Authenticate header had been received at that URI.
+ *
+ * This can be used to "preload" @manager's auth cache, to avoid an extra HTTP
+ * round trip in the case where you know ahead of time that a 401 response will
+ * be returned.
  *
  * This is only useful for authentication types where the initial
  * Authorization header does not depend on any additional information
@@ -851,7 +838,7 @@ soup_auth_manager_use_auth (SoupAuthManager *manager,
  * soup_auth_manager_clear_cached_credentials:
  * @manager: a #SoupAuthManager
  *
- * Clear all credentials cached by @manager
+ * Clear all credentials cached by @manager.
  *
  */
 void
diff --git a/libsoup/auth/soup-auth-negotiate.c b/libsoup/auth/soup-auth-negotiate.c
index a5624a3d..817ba5f5 100644
--- a/libsoup/auth/soup-auth-negotiate.c
+++ b/libsoup/auth/soup-auth-negotiate.c
@@ -27,9 +27,10 @@
 /**
  * soup_auth_negotiate_supported:
  *
- * Indicates whether libsoup was built with GSSAPI support. If this is
- * %FALSE, %SOUP_TYPE_AUTH_NEGOTIATE will still be defined and can
- * still be added to a #SoupSession, but libsoup will never attempt to
+ * Indicates whether libsoup was built with GSSAPI support.
+ *
+ * If this is %FALSE, %SOUP_TYPE_AUTH_NEGOTIATE will still be defined and can
+ * still be added to a [class@Session], but libsoup will never attempt to
  * actually use this auth type.
  *
  */
@@ -76,17 +77,17 @@ typedef struct {
 } SoupAuthNegotiatePrivate;
 
 /**
- * SOUP_TYPE_AUTH_NEGOTIATE:
+ * SoupAuthNegotiate:
+ *
+ * HTTP-based GSS-Negotiate authentication.
  *
- * A #GType corresponding to HTTP-based GSS-Negotiate authentication.
- * #SoupSessions do not support this type by default; if you want to
- * enable support for it, call soup_session_add_feature_by_type(),
+ * [class@Session]s do not support this type by default; if you want to
+ * enable support for it, call [method@Session.add_feature_by_type],
  * passing %SOUP_TYPE_AUTH_NEGOTIATE.
  *
  * This auth type will only work if libsoup was compiled with GSSAPI
- * support; you can check soup_auth_negotiate_supported() to see if it
+ * support; you can check [func@AuthNegotiate.supported] to see if it
  * was.
- *
  */
 G_DEFINE_FINAL_TYPE_WITH_PRIVATE (SoupAuthNegotiate, soup_auth_negotiate, SOUP_TYPE_CONNECTION_AUTH)
 
diff --git a/libsoup/auth/soup-auth-ntlm.c b/libsoup/auth/soup-auth-ntlm.c
index 457cc98b..895e5d6d 100644
--- a/libsoup/auth/soup-auth-ntlm.c
+++ b/libsoup/auth/soup-auth-ntlm.c
@@ -99,13 +99,13 @@ static void sso_ntlm_close (SoupAuthNTLMPrivate *priv);
 #endif
 
 /**
- * SOUP_TYPE_AUTH_NTLM:
+ * SoupAuthNTLM:
  *
- * 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.
+ * HTTP-based NTLM authentication.
  *
+ * [class@Session]s do not support this type by default; if you want to
+ * enable support for it, call [method@Session.add_feature_by_type],
+ * passing %SOUP_TYPE_AUTH_NTLM.
  */
 
 G_DEFINE_FINAL_TYPE_WITH_PRIVATE (SoupAuthNTLM, soup_auth_ntlm, SOUP_TYPE_CONNECTION_AUTH)
diff --git a/libsoup/auth/soup-auth.c b/libsoup/auth/soup-auth.c
index d9bf4afe..b9de5e9a 100644
--- a/libsoup/auth/soup-auth.c
+++ b/libsoup/auth/soup-auth.c
@@ -18,22 +18,16 @@
 #include "soup-uri-utils-private.h"
 
 /**
- * SECTION:soup-auth
- * @short_description: HTTP client-side authentication support
- * @see_also: #SoupSession
- *
- * #SoupAuth objects store the authentication data associated with a
- * given bit of web space. They are created automatically by
- * #SoupSession.
- **/
-
-/**
  * SoupAuth:
  *
- * The abstract base class for handling authentication. Specific HTTP
- * Authentication mechanisms are implemented by its subclasses, but
- * applications never need to be aware of the specific subclasses
- * being used.
+ * The abstract base class for handling authentication.
+ *
+ * Specific HTTP Authentication mechanisms are implemented by its subclasses,
+ * but applications never need to be aware of the specific subclasses being
+ * used.
+ *
+ * #SoupAuth objects store the authentication data associated with a given bit
+ * of web space. They are created automatically by [class@Session].
  **/
 
 typedef struct {
@@ -166,7 +160,7 @@ soup_auth_class_init (SoupAuthClass *auth_class)
 
 	/* properties */
 	/**
-	 * SoupAuth:scheme-name:
+         * SoupAuth:scheme-name: (attributes org.gtk.Property.get=soup_auth_get_scheme_name)
          *
          * The authentication scheme name.
 	 **/
@@ -178,7 +172,7 @@ soup_auth_class_init (SoupAuthClass *auth_class)
 				     G_PARAM_READABLE |
 				     G_PARAM_STATIC_STRINGS);
 	/**
-	 * SoupAuth:realm:
+	 * SoupAuth:realm: (attributes org.gtk.Property.get=soup_auth_get_realm)
 	 *
 	 * The authentication realm.
 	 **/
@@ -190,7 +184,7 @@ soup_auth_class_init (SoupAuthClass *auth_class)
 				     G_PARAM_READWRITE |
 				     G_PARAM_STATIC_STRINGS);
 	/**
-	 * SoupAuth:authority:
+	 * SoupAuth:authority: (attributes org.gtk.Property.get=soup_auth_get_authority)
 	 *
 	 * The authority (host:port) being authenticated to.
 	 **/
@@ -202,7 +196,7 @@ soup_auth_class_init (SoupAuthClass *auth_class)
 				     G_PARAM_READWRITE |
 				     G_PARAM_STATIC_STRINGS);
 	/**
-	 * SoupAuth:is-for-proxy:
+	 * SoupAuth:is-for-proxy: (attributes org.gtk.Property.get=soup_auth_is_for_proxy)
 	 *
 	 * Whether or not the auth is for a proxy server.
 	 **/
@@ -214,7 +208,7 @@ soup_auth_class_init (SoupAuthClass *auth_class)
 				      G_PARAM_READWRITE |
 				      G_PARAM_STATIC_STRINGS);
 	/**
-	 * SoupAuth:is-authenticated:
+	 * SoupAuth:is-authenticated: (attributes org.gtk.Property.get=soup_auth_is_authenticated)
 	 *
 	 * Whether or not the auth has been authenticated.
 	 **/
@@ -226,10 +220,9 @@ soup_auth_class_init (SoupAuthClass *auth_class)
 				      G_PARAM_READABLE |
 				      G_PARAM_STATIC_STRINGS);
 	/**
-	 * SoupAuth:is-cancelled:
+	 * SoupAuth:is-cancelled: (attributes org.gtk.Property.get=soup_auth_is_cancelled)
 	 *
-	 * An alias for the #SoupAuth:is-cancelled property.
-	 * (Whether or not the auth has been cancelled.)
+	 * Whether or not the auth has been cancelled.
 	 **/
         properties[PROP_IS_CANCELLED] =
 		g_param_spec_boolean ("is-cancelled",
@@ -251,11 +244,11 @@ soup_auth_class_init (SoupAuthClass *auth_class)
  * Creates a new #SoupAuth of type @type with the information from
  * @msg and @auth_header.
  *
- * This is called by #SoupSession; you will normally not create auths
+ * This is called by [class@Session]; you will normally not create auths
  * yourself.
  *
  * Returns: (nullable): the new #SoupAuth, or %NULL if it could
- * not be created
+ *   not be created
  **/
 SoupAuth *
 soup_auth_new (GType type, SoupMessage *msg, const char *auth_header)
@@ -310,12 +303,13 @@ soup_auth_new (GType type, SoupMessage *msg, const char *auth_header)
  * @auth_header: the WWW-Authenticate/Proxy-Authenticate header
  *
  * Updates @auth with the information from @msg and @auth_header,
- * possibly un-authenticating it. As with soup_auth_new(), this is
- * normally only used by #SoupSession.
+ * possibly un-authenticating it.
+ *
+ * As with [ctor@Auth.new], this is normally only used by [class@Session].
  *
  * Returns: %TRUE if @auth is still a valid (but potentially
- * unauthenticated) #SoupAuth. %FALSE if something about @auth_params
- * could not be parsed or incorporated into @auth at all.
+ *   unauthenticated) #SoupAuth. %FALSE if something about @auth_params
+ *   could not be parsed or incorporated into @auth at all.
  **/
 gboolean
 soup_auth_update (SoupAuth *auth, SoupMessage *msg, const char *auth_header)
@@ -360,8 +354,10 @@ soup_auth_update (SoupAuth *auth, SoupMessage *msg, const char *auth_header)
  * @username: the username provided by the user or client
  * @password: the password provided by the user or client
  *
- * Call this on an auth to authenticate it; normally this will cause
- * the auth's message to be requeued with the new authentication info.
+ * Call this on an auth to authenticate it.
+ *
+ * Normally this will cause the auth's message to be requeued with the new
+ * authentication info.
  **/
 void
 soup_auth_authenticate (SoupAuth *auth, const char *username, const char *password)
@@ -387,9 +383,10 @@ soup_auth_authenticate (SoupAuth *auth, const char *username, const char *passwo
  * soup_auth_cancel:
  * @auth: a #SoupAuth
  *
- * Call this on an auth to cancel it. You need to cancel an auth to complete
- * an asynchronous authenticate operation when no credentials are provided
- * (soup_auth_authenticate() is not called).
+ * Call this on an auth to cancel it.
+ *
+ * You need to cancel an auth to complete an asynchronous authenticate operation
+ * when no credentials are provided ([method@Auth.authenticate] is not called).
  * The #SoupAuth will be cancelled on dispose if it hans't been authenticated.
  */
 void
@@ -408,7 +405,7 @@ soup_auth_cancel (SoupAuth *auth)
 }
 
 /**
- * soup_auth_is_for_proxy:
+ * soup_auth_is_for_proxy: (attributes org.gtk.Method.get_property=is-for-proxy)
  * @auth: a #SoupAuth
  *
  * Tests whether or not @auth is associated with a proxy server rather
@@ -428,6 +425,7 @@ soup_auth_is_for_proxy (SoupAuth *auth)
 
 /**
  * soup_auth_get_scheme_name:
+ * soup_auth_get_scheme_name: (attributes org.gtk.Method.get_property=scheme-name)
  * @auth: a #SoupAuth
  *
  * Returns @auth's scheme name. (Eg, "Basic", "Digest", or "NTLM")
@@ -443,7 +441,7 @@ soup_auth_get_scheme_name (SoupAuth *auth)
 }
 
 /**
- * soup_auth_get_authority:
+ * soup_auth_get_authority: (attributes org.gtk.Method.get_property=authority)
  * @auth: a #SoupAuth
  *
  * Returns the authority (host:port) that @auth is associated with.
@@ -461,13 +459,14 @@ soup_auth_get_authority (SoupAuth *auth)
 }
 
 /**
- * soup_auth_get_realm:
+ * soup_auth_get_realm: (attributes org.gtk.Method.get_property=realm)
  * @auth: a #SoupAuth
  *
- * Returns @auth's realm. This is an identifier that distinguishes
- * separate authentication spaces on a given server, and may be some
- * string that is meaningful to the user. (Although it is probably not
- * localized.)
+ * Returns @auth's realm.
+ *
+ * This is an identifier that distinguishes separate authentication spaces on a
+ * given server, and may be some string that is meaningful to the user.
+ * (Although it is probably not localized.)
  *
  * Returns: the realm name
  **/
@@ -485,10 +484,12 @@ soup_auth_get_realm (SoupAuth *auth)
  * soup_auth_get_info:
  * @auth: a #SoupAuth
  *
- * Gets an opaque identifier for @auth, for use as a hash key or the
- * like. #SoupAuth objects from the same server with the same
- * identifier refer to the same authentication domain (eg, the URLs
- * associated with them take the same usernames and passwords).
+ * Gets an opaque identifier for @auth.
+ *
+ * The identifier can be used as a hash key or the like. #SoupAuth objects from
+ * the same server with the same identifier refer to the same authentication
+ * domain (eg, the URLs associated with them take the same usernames and
+ * passwords).
  *
  * Returns: the identifier
  **/
@@ -509,10 +510,10 @@ soup_auth_get_info (SoupAuth *auth)
 }
 
 /**
- * soup_auth_is_authenticated:
+ * soup_auth_is_authenticated: (attributes org.gtk.Method.get_property=is-authenticated)
  * @auth: a #SoupAuth
  *
- * Tests if @auth has been given a username and password
+ * Tests if @auth has been given a username and password.
  *
  * Returns: %TRUE if @auth has been given a username and password
  **/
@@ -531,7 +532,7 @@ soup_auth_is_authenticated (SoupAuth *auth)
 }
 
 /**
- * soup_auth_is_cancelled:
+ * soup_auth_is_cancelled: (attributes org.gtk.Method.get_property=is-cancelled)
  * @auth: a #SoupAuth
  *
  * Tests if @auth has been cancelled
@@ -554,9 +555,10 @@ soup_auth_is_cancelled (SoupAuth *auth)
  * @auth: a #SoupAuth
  * @msg: the #SoupMessage to be authorized
  *
- * Generates an appropriate "Authorization" header for @msg. (The
- * session will only call this if soup_auth_is_authenticated()
- * returned %TRUE.)
+ * Generates an appropriate "Authorization" header for @msg.
+ *
+ * (The session will only call this if [method@Auth.is_authenticated] returned
+ * %TRUE.)
  *
  * Returns: the "Authorization" header, which must be freed.
  **/
@@ -574,8 +576,9 @@ soup_auth_get_authorization (SoupAuth *auth, SoupMessage *msg)
  * @auth: a #SoupAuth
  * @msg: a #SoupMessage
  *
- * Tests if @auth is ready to make a request for @msg with. For most
- * auths, this is equivalent to soup_auth_is_authenticated(), but for
+ * Tests if @auth is ready to make a request for @msg with.
+ *
+ * For most auths, this is equivalent to [method@Auth.is_authenticated], but for
  * some auth types (eg, NTLM), the auth may be sendable (eg, as an
  * authentication request) even before it is authenticated.
  *
@@ -606,7 +609,7 @@ soup_auth_is_ready (SoupAuth    *auth,
  * @auth: a #SoupAuth
  *
  * Tests if @auth is able to authenticate by providing credentials to the
- * soup_auth_authenticate().
+ * [method@Auth.authenticate].
  *
  * Returns: %TRUE if @auth is able to accept credentials.
  *
@@ -629,15 +632,16 @@ soup_auth_can_authenticate (SoupAuth *auth)
  * soup_auth_get_protection_space:
  * @auth: a #SoupAuth
  * @source_uri: the URI of the request that @auth was generated in
- * response to.
+ *   response to.
  *
  * Returns a list of paths on the server which @auth extends over.
+ *
  * (All subdirectories of these paths are also assumed to be part
  * of @auth's protection space, unless otherwise discovered not to
  * be.)
  *
  * Returns: (element-type utf8) (transfer full): the list of
- * paths, which can be freed with soup_auth_free_protection_space().
+ *   paths, which can be freed with [method@Auth.free_protection_space].
  **/
 GSList *
 soup_auth_get_protection_space (SoupAuth *auth, GUri *source_uri)
@@ -654,7 +658,7 @@ soup_auth_get_protection_space (SoupAuth *auth, GUri *source_uri)
 /**
  * soup_auth_free_protection_space: (skip)
  * @auth: a #SoupAuth
- * @space: the return value from soup_auth_get_protection_space()
+ * @space: the return value from [method@Auth.get_protection_space]
  *
  * Frees @space.
  **/
diff --git a/libsoup/cache/soup-cache.c b/libsoup/cache/soup-cache.c
index ddd215b1..3b557186 100644
--- a/libsoup/cache/soup-cache.c
+++ b/libsoup/cache/soup-cache.c
@@ -47,16 +47,9 @@
 #include "soup-session-feature-private.h"
 
 /**
- * SECTION:soup-cache
- * @short_description: Caching support
- *
- * #SoupCache implements a file-based cache for HTTP resources.
- */
-
-/**
  * SoupCache:
  *
- * Class implementing caching for HTTP resources.
+ * File-based cache for HTTP resources.
  */
 
 static void soup_cache_session_feature_init (SoupSessionFeatureInterface *feature_interface, gpointer interface_data);
@@ -1255,8 +1248,8 @@ soup_cache_has_response (SoupCache *cache, SoupMessage *msg)
  *
  * Calculates whether the @msg can be cached or not.
  *
- * Returns: a #SoupCacheability value indicating whether the @msg can be cached or not.
- *
+ * Returns: a #SoupCacheability value indicating whether the @msg can be cached
+ *   or not.
  */
 SoupCacheability
 soup_cache_get_cacheability (SoupCache *cache, SoupMessage *msg)
@@ -1280,13 +1273,13 @@ force_flush_timeout (gpointer data)
  * soup_cache_flush:
  * @cache: a #SoupCache
  *
- * This function will force all pending writes in the @cache to be
- * committed to disk. For doing so it will iterate the #GMainContext
- * associated with @cache's session as long as needed.
+ * Forces all pending writes in the @cache to be
+ * committed to disk.
  *
- * Contrast with soup_cache_dump(), which writes out the cache index
- * file.
+ * For doing so it will iterate the [struct@GLib.MainContext] associated with
+ * @cache's session as long as needed.
  *
+ * Contrast with [method@Cache.dump], which writes out the cache index file.
  */
 void
 soup_cache_flush (SoupCache *cache)
@@ -1365,7 +1358,6 @@ clear_cache_files (SoupCache *cache)
  * @cache: a #SoupCache
  *
  * Will remove all entries in the @cache plus all the cache files.
- *
  */
 void
 soup_cache_clear (SoupCache *cache)
@@ -1509,13 +1501,13 @@ pack_entry (gpointer data,
  * 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.
+ * Synchronously writes the cache index out to disk.
+ *
+ * Contrast with [method@Cache.flush], which writes pending cache *entries* to
+ * disk.
  *
  * You must call this before exiting if you want your cache data to
  * persist between sessions.
- *
  */
 void
 soup_cache_dump (SoupCache *cache)
@@ -1577,7 +1569,6 @@ insert_cache_file (SoupCache *cache, const char *name, GHashTable *leaked_entrie
  * @cache: a #SoupCache
  *
  * Loads the contents of @cache's index into memory.
- *
  */
 void
 soup_cache_load (SoupCache *cache)
@@ -1676,7 +1667,6 @@ soup_cache_load (SoupCache *cache)
  * @max_size: the maximum size of the cache, in bytes
  *
  * Sets the maximum size of the cache.
- *
  */
 void
 soup_cache_set_max_size (SoupCache *cache,
@@ -1694,7 +1684,6 @@ soup_cache_set_max_size (SoupCache *cache,
  * Gets the maximum size of the cache.
  *
  * Returns: the maximum size of the cache, in bytes.
- *
  */
 guint
 soup_cache_get_max_size (SoupCache *cache)
diff --git a/libsoup/content-decoder/soup-content-decoder.c b/libsoup/content-decoder/soup-content-decoder.c
index 5be17c6e..f75ebce4 100644
--- a/libsoup/content-decoder/soup-content-decoder.c
+++ b/libsoup/content-decoder/soup-content-decoder.c
@@ -21,8 +21,9 @@
 #endif
 
 /**
- * SECTION:soup-content-decoder
- * @short_description: Content-Encoding handler
+ * SoupContentDecoder:
+ *
+ * Handles decoding of HTTP messages.
  *
  * #SoupContentDecoder handles adding the "Accept-Encoding" header on
  * outgoing messages, and processing the "Content-Encoding" header on
@@ -31,7 +32,7 @@
  *
  * A #SoupContentDecoder will automatically be
  * added to the session by default. (You can use
- * soup_session_remove_feature_by_type() if you don't
+ * [method@Session.remove_feature_by_type] if you don't
  * want this.)
  *
  * If #SoupContentDecoder successfully decodes the Content-Encoding,
@@ -46,15 +47,8 @@
  * (Note that currently there is no way to (automatically) use
  * Content-Encoding when sending a request body, or to pick specific
  * encoding types to support.)
- *
  **/
 
-/**
- * SoupContentDecoder:
- *
- * Class handling decoding of HTTP messages.
- */
-
 struct _SoupContentDecoder {
 	GObject parent;
 };
diff --git a/libsoup/content-sniffer/soup-content-sniffer.c b/libsoup/content-sniffer/soup-content-sniffer.c
index 243d52e8..4eb27bc5 100644
--- a/libsoup/content-sniffer/soup-content-sniffer.c
+++ b/libsoup/content-sniffer/soup-content-sniffer.c
@@ -24,24 +24,18 @@
 #include "soup-session-feature-private.h"
 
 /**
- * SECTION:soup-content-sniffer
- * @short_description: Content sniffing for SoupSession
+ * SoupContentSniffer:
+ *
+ * Sniffs the mime type of messages.
  *
  * A #SoupContentSniffer tries to detect the actual content type of
  * the files that are being downloaded by looking at some of the data
- * before the #SoupMessage emits its #SoupMessage::got-headers signal.
- * #SoupContentSniffer implements #SoupSessionFeature, so you can add
- * content sniffing to a session with soup_session_add_feature() or
- * soup_session_add_feature_by_type().
- *
+ * before the [class@Message] emits its [signal@Message::got-headers] signal.
+ * #SoupContentSniffer implements [iface@SessionFeature], so you can add
+ * content sniffing to a session with [method@Session.add_feature] or
+ * [method@Session.add_feature_by_type].
  **/
 
-/**
- * SoupContentSniffer:
- *
- * Class that attempts to sniff the mime type of messages.
- */
-
 static void soup_content_sniffer_session_feature_init (SoupSessionFeatureInterface *feature_interface, gpointer interface_data);
 
 static SoupContentProcessorInterface *soup_content_sniffer_default_content_processor_interface;
@@ -787,13 +781,13 @@ sniff_feed_or_html (SoupContentSniffer *sniffer, GBytes *buffer)
  * @params: (element-type utf8 utf8) (out) (transfer full) (nullable): return
  *   location for Content-Type parameters (eg, "charset"), or %NULL
  *
- * Sniffs @buffer to determine its Content-Type. The result may also
- * be influenced by the Content-Type declared in @msg's response
- * headers.
+ * Sniffs @buffer to determine its Content-Type.
  *
- * Returns: the sniffed Content-Type of @buffer; this will never be %NULL,
- *   but may be "application/octet-stream".
+ * The result may also be influenced by the Content-Type declared in @msg's
+ * response headers.
  *
+ * Returns: the sniffed Content-Type of @buffer; this will never be %NULL,
+ *   but may be `application/octet-stream`.
  */
 char *
 soup_content_sniffer_sniff (SoupContentSniffer *sniffer, SoupMessage *msg,
@@ -901,7 +895,6 @@ soup_content_sniffer_session_feature_init (SoupSessionFeatureInterface *feature_
  * Creates a new #SoupContentSniffer.
  *
  * Returns: a new #SoupContentSniffer
- *
  **/
 SoupContentSniffer *
 soup_content_sniffer_new (void)
diff --git a/libsoup/cookies/soup-cookie-jar-db.c b/libsoup/cookies/soup-cookie-jar-db.c
index 91fa15d3..d2a78a78 100644
--- a/libsoup/cookies/soup-cookie-jar-db.c
+++ b/libsoup/cookies/soup-cookie-jar-db.c
@@ -19,23 +19,18 @@
 #include "soup.h"
 
 /**
- * SECTION:soup-cookie-jar-db
- * @short_description: Database-based Cookie Jar
+ * SoupCookieJarDB:
+ *
+ * Database-based Cookie Jar.
  *
- * #SoupCookieJarDB is a #SoupCookieJar that reads cookies from and
- * writes them to a sqlite database in the new Mozilla format.
+ * #SoupCookieJarDB is a [class@CookieJar] that reads cookies from and writes
+ * them to a sqlite database in the new Mozilla format.
  *
- * (This is identical to <literal>SoupCookieJarSqlite</literal> in
+ * (This is identical to `SoupCookieJarSqlite` in
  * libsoup-gnome; it has just been moved into libsoup proper, and
  * renamed to avoid conflicting.)
  **/
 
-/**
- * SoupCookieJarDB:
- *
- * Subclass of #SoupCookieJar that stores cookies in a sqlite database.
- */
-
 enum {
 	PROP_0,
 
@@ -119,15 +114,13 @@ soup_cookie_jar_db_get_property (GObject *object, guint prop_id,
  *
  * Creates a #SoupCookieJarDB.
  *
- * @filename will be read in at startup to create an initial set of
- * cookies. If @read_only is %FALSE, then the non-session cookies will
- * be written to @filename when the 'changed' signal is emitted from
- * the jar. (If @read_only is %TRUE, then the cookie jar will only be
- * used for this session, and changes made to it will be lost when the
- * jar is destroyed.)
+ * @filename will be read in at startup to create an initial set of cookies. If
+ * @read_only is %FALSE, then the non-session cookies will be written to
+ * @filename when the [signal@CookieJar::changed] signal is emitted from the
+ * jar. (If @read_only is %TRUE, then the cookie jar will only be used for this
+ * session, and changes made to it will be lost when the jar is destroyed.)
  *
  * Returns: the new #SoupCookieJar
- *
  **/
 SoupCookieJar *
 soup_cookie_jar_db_new (const char *filename, gboolean read_only)
@@ -339,6 +332,11 @@ soup_cookie_jar_db_class_init (SoupCookieJarDBClass *db_class)
 	object_class->set_property = soup_cookie_jar_db_set_property;
 	object_class->get_property = soup_cookie_jar_db_get_property;
 
+	/**
+	 * SoupCookieJarDB:filename:
+	 *
+	 * Cookie-storage filename.
+	 */
         properties[PROP_FILENAME] =
 		g_param_spec_string ("filename",
 				     "Filename",
diff --git a/libsoup/cookies/soup-cookie-jar-text.c b/libsoup/cookies/soup-cookie-jar-text.c
index ab882ea8..274da259 100644
--- a/libsoup/cookies/soup-cookie-jar-text.c
+++ b/libsoup/cookies/soup-cookie-jar-text.c
@@ -17,18 +17,13 @@
 #include "soup.h"
 
 /**
- * SECTION:soup-cookie-jar-text
- * @short_description: Text-file-based ("cookies.txt") Cookie Jar
- *
- * #SoupCookieJarText is a #SoupCookieJar that reads cookies from and
- * writes them to a text file in format similar to Mozilla's "cookies.txt".
- **/
-
-/**
  * SoupCookieJarText:
  *
- * Subclass of #SoupCookieJar that stores cookies in a text file.
- */
+ * Text-file-based ("cookies.txt") Cookie Jar
+ *
+ * #SoupCookieJarText is a [class@CookieJar] that reads cookies from and writes
+ * them to a text file in format similar to Mozilla's "cookies.txt".
+ **/
 
 enum {
 	PROP_0,
@@ -113,15 +108,13 @@ soup_cookie_jar_text_get_property (GObject *object, guint prop_id,
  *
  * Creates a #SoupCookieJarText.
  *
- * @filename will be read in at startup to create an initial set of
- * cookies. If @read_only is %FALSE, then the non-session cookies will
- * be written to @filename when the 'changed' signal is emitted from
- * the jar. (If @read_only is %TRUE, then the cookie jar will only be
- * used for this session, and changes made to it will be lost when the
- * jar is destroyed.)
+ * @filename will be read in at startup to create an initial set of cookies. If
+ * @read_only is %FALSE, then the non-session cookies will be written to
+ * @filename when the [signal@CookieJar::changed] signal is emitted from the
+ * jar. (If @read_only is %TRUE, then the cookie jar will only be used for this
+ * session, and changes made to it will be lost when the jar is destroyed.)
  *
  * Returns: the new #SoupCookieJar
- *
  **/
 SoupCookieJar *
 soup_cookie_jar_text_new (const char *filename, gboolean read_only)
@@ -394,6 +387,11 @@ soup_cookie_jar_text_class_init (SoupCookieJarTextClass *text_class)
 	object_class->set_property = soup_cookie_jar_text_set_property;
 	object_class->get_property = soup_cookie_jar_text_get_property;
 
+	/**
+	 * SoupCookieJarText:filename:
+	 *
+	 * Cookie-storage filename.
+	 */
         properties[PROP_FILENAME] =
 		g_param_spec_string ("filename",
 				     "Filename",
diff --git a/libsoup/cookies/soup-cookie-jar.c b/libsoup/cookies/soup-cookie-jar.c
index 6b6c5f4f..c14f90ab 100644
--- a/libsoup/cookies/soup-cookie-jar.c
+++ b/libsoup/cookies/soup-cookie-jar.c
@@ -21,25 +21,19 @@
 #include "soup-uri-utils-private.h"
 
 /**
- * SECTION:soup-cookie-jar
- * @short_description: Automatic cookie handling for SoupSession
+ * SoupCookieJar:
+ *
+ * Automatic cookie handling for SoupSession.
  *
- * A #SoupCookieJar stores #SoupCookie<!-- -->s and arrange for them
- * to be sent with the appropriate #SoupMessage<!-- -->s.
- * #SoupCookieJar implements #SoupSessionFeature, so you can add a
- * cookie jar to a session with soup_session_add_feature() or
- * soup_session_add_feature_by_type().
+ * A #SoupCookieJar stores [struct@Cookie]s and arrange for them to be sent with
+ * the appropriate [class@Message]s. #SoupCookieJar implements
+ * [iface@SessionFeature], so you can add a cookie jar to a session with
+ * [method@Session.add_feature] or [method@Session.add_feature_by_type].
  *
  * Note that the base #SoupCookieJar class does not support any form
  * of long-term cookie persistence.
  **/
 
-/**
- * SoupCookieJar:
- *
- * Class that stores cookies in memory.
- */
-
 enum {
 	CHANGED,
 	LAST_SIGNAL
@@ -174,7 +168,9 @@ soup_cookie_jar_class_init (SoupCookieJarClass *jar_class)
 	 * @old_cookie: the old #SoupCookie value
 	 * @new_cookie: the new #SoupCookie value
 	 *
-	 * Emitted when @jar changes. If a cookie has been added,
+	 * Emitted when @jar changes.
+	 *
+	 * If a cookie has been added,
 	 * @new_cookie will contain the newly-added cookie and
 	 * @old_cookie will be %NULL. If a cookie has been deleted,
 	 * @old_cookie will contain the to-be-deleted cookie and
@@ -193,6 +189,11 @@ soup_cookie_jar_class_init (SoupCookieJarClass *jar_class)
 			      SOUP_TYPE_COOKIE | G_SIGNAL_TYPE_STATIC_SCOPE,
 			      SOUP_TYPE_COOKIE | G_SIGNAL_TYPE_STATIC_SCOPE);
 
+	/**
+	 * SoupCookieJar:read-only:
+	 *
+	 * Whether or not the cookie jar is read-only.
+	 */
         properties[PROP_READ_ONLY] =
 		g_param_spec_boolean ("read-only",
 				      "Read-only",
@@ -202,10 +203,9 @@ soup_cookie_jar_class_init (SoupCookieJarClass *jar_class)
 				      G_PARAM_STATIC_STRINGS);
 
 	/**
-	 * SoupCookieJar:accept-policy:
-	 *
-	 * The policy the jar should follow to accept or reject cookies
+	 * SoupCookieJar:accept-policy: (attributes org.gtk.Property.get=soup_cookie_jar_get_accept_policy org.gtk.Property.set=soup_cookie_jar_set_accept_policy)
 	 *
+	 * The policy the jar should follow to accept or reject cookies.
 	 */
         properties[PROP_ACCEPT_POLICY] =
 		g_param_spec_enum ("accept-policy",
@@ -222,11 +222,12 @@ soup_cookie_jar_class_init (SoupCookieJarClass *jar_class)
 /**
  * soup_cookie_jar_new:
  *
- * Creates a new #SoupCookieJar. The base #SoupCookieJar class does
- * not support persistent storage of cookies; use a subclass for that.
+ * Creates a new #SoupCookieJar.
  *
- * Returns: a new #SoupCookieJar
+ * The base #SoupCookieJar class does not support persistent storage of cookies;
+ * use a subclass for that.
  *
+ * Returns: a new #SoupCookieJar
  **/
 SoupCookieJar *
 soup_cookie_jar_new (void) 
@@ -385,7 +386,7 @@ get_cookies (SoupCookieJar *jar,
  * @jar: a #SoupCookieJar
  * @uri: a #GUri
  * @for_http: whether or not the return value is being passed directly
- * to an HTTP operation
+ *   to an HTTP operation
  *
  * Retrieves (in Cookie-header form) the list of cookies that would
  * be sent with a request to @uri.
@@ -399,8 +400,7 @@ get_cookies (SoupCookieJar *jar,
  * this.
  *
  * Returns: (nullable): the cookies, in string form, or %NULL if
- * there are no cookies for @uri.
- *
+ *   there are no cookies for @uri.
  **/
 char *
 soup_cookie_jar_get_cookies (SoupCookieJar *jar, GUri *uri,
@@ -431,10 +431,10 @@ soup_cookie_jar_get_cookies (SoupCookieJar *jar, GUri *uri,
  * @jar: a #SoupCookieJar
  * @uri: a #GUri
  * @for_http: whether or not the return value is being passed directly
- * to an HTTP operation
+ *   to an HTTP operation
  *
  * Retrieves the list of cookies that would be sent with a request to @uri
- * as a #GSList of #SoupCookie objects.
+ * as a [struct@GLib.List] of #SoupCookie objects.
  *
  * If @for_http is %TRUE, the return value will include cookies marked
  * "HttpOnly" (that is, cookies that the server wishes to keep hidden
@@ -445,8 +445,7 @@ soup_cookie_jar_get_cookies (SoupCookieJar *jar, GUri *uri,
  * this.
  *
  * Returns: (transfer full) (element-type Soup.Cookie): a #GSList
- * with the cookies in the @jar that would be sent with a request to @uri.
- *
+ *   with the cookies in the @jar that would be sent with a request to @uri.
  **/
 GSList *
 soup_cookie_jar_get_cookie_list (SoupCookieJar *jar, GUri *uri, gboolean for_http)
@@ -464,19 +463,20 @@ soup_cookie_jar_get_cookie_list (SoupCookieJar *jar, GUri *uri, gboolean for_htt
  * @top_level: (nullable): a #GUri for the top level document
  * @site_for_cookies: (nullable): a #GUri indicating the origin to get cookies for
  * @for_http: whether or not the return value is being passed directly
- * to an HTTP operation
+ *   to an HTTP operation
  * @is_safe_method: if the HTTP method is safe, as defined by RFC 7231, ignored when @for_http is %FALSE
  * @is_top_level_navigation: whether or not the HTTP request is part of
- * top level navigation
+ *   top level navigation
  *
- * This is an extended version of soup_cookie_jar_get_cookie_list() that
- * provides more information required to use SameSite cookies. See the
- * [SameSite cookies spec](https://tools.ietf.org/html/draft-ietf-httpbis-cookie-same-site-00)
- * for more detailed information.
+ * This is an extended version of [method@CookieJar.get_cookie_list] that
+ * provides more information required to use SameSite cookies.
  *
- * Returns: (transfer full) (element-type Soup.Cookie): a #GSList
- * with the cookies in the @jar that would be sent with a request to @uri.
+ * See the [SameSite cookies
+ * spec](https://tools.ietf.org/html/draft-ietf-httpbis-cookie-same-site-00) for
+ * more detailed information.
  *
+ * Returns: (transfer full) (element-type Soup.Cookie): a #GSList
+ *   with the cookies in the @jar that would be sent with a request to @uri.
  */
 GSList *
 soup_cookie_jar_get_cookie_list_with_same_site_info (SoupCookieJar *jar,
@@ -559,9 +559,11 @@ incoming_cookie_is_third_party (SoupCookieJar            *jar,
  * @uri: (nullable): the URI setting the cookie
  * @first_party: (nullable): the URI for the main document
  *
- * Adds @cookie to @jar, emitting the 'changed' signal if we are modifying
- * an existing cookie or adding a valid new cookie ('valid' means
- * that the cookie's expire date is not in the past).
+ * Adds @cookie to @jar.
+ *
+ * Emits the [signal@CookieJar::changed] signal if we are modifying an existing
+ * cookie or adding a valid new cookie ('valid' means that the cookie's expire
+ * date is not in the past).
  *
  * @first_party will be used to reject cookies coming from third party
  * resources in case such a security policy is set in the @jar.
@@ -570,7 +572,6 @@ incoming_cookie_is_third_party (SoupCookieJar            *jar,
  * from insecure origins. %NULL is treated as secure.
  * 
  * @cookie will be 'stolen' by the jar, so don't free it afterwards.
- *
  **/
 void
 soup_cookie_jar_add_cookie_full (SoupCookieJar *jar, SoupCookie *cookie, GUri *uri, GUri *first_party)
@@ -661,12 +662,13 @@ soup_cookie_jar_add_cookie_full (SoupCookieJar *jar, SoupCookie *cookie, GUri *u
  * @jar: a #SoupCookieJar
  * @cookie: (transfer full): a #SoupCookie
  *
- * Adds @cookie to @jar, emitting the 'changed' signal if we are modifying
+ * Adds @cookie to @jar.
+ *
+ * Emits the [signal@CookieJar::changed] signal if we are modifying
  * an existing cookie or adding a valid new cookie ('valid' means
  * that the cookie's expire date is not in the past).
  *
  * @cookie will be 'stolen' by the jar, so don't free it afterwards.
- *
  **/
 void
 soup_cookie_jar_add_cookie (SoupCookieJar *jar, SoupCookie *cookie)
@@ -680,7 +682,9 @@ soup_cookie_jar_add_cookie (SoupCookieJar *jar, SoupCookie *cookie)
  * @first_party: the URI for the main document
  * @cookie: (transfer full): a #SoupCookie
  *
- * Adds @cookie to @jar, emitting the 'changed' signal if we are modifying
+ * Adds @cookie to @jar.
+ *
+ * Emits the [signal@CookieJar::changed] signal if we are modifying
  * an existing cookie or adding a valid new cookie ('valid' means
  * that the cookie's expire date is not in the past).
  *
@@ -690,8 +694,7 @@ soup_cookie_jar_add_cookie (SoupCookieJar *jar, SoupCookie *cookie)
  * @cookie will be 'stolen' by the jar, so don't free it afterwards.
  *
  * For secure cookies to work properly you may want to use
- * soup_cookie_jar_add_cookie_full().
- *
+ * [method@CookieJar.add_cookie_full].
  **/
 void
 soup_cookie_jar_add_cookie_with_first_party (SoupCookieJar *jar, GUri *first_party, SoupCookie *cookie)
@@ -710,13 +713,12 @@ soup_cookie_jar_add_cookie_with_first_party (SoupCookieJar *jar, GUri *first_par
  * Adds @cookie to @jar, exactly as though it had appeared in a
  * Set-Cookie header returned from a request to @uri.
  *
- * Keep in mind that if the #SoupCookieJarAcceptPolicy set is either
+ * Keep in mind that if the [enum@CookieJarAcceptPolicy] set is either
  * %SOUP_COOKIE_JAR_ACCEPT_NO_THIRD_PARTY or
  * %SOUP_COOKIE_JAR_ACCEPT_GRANDFATHERED_THIRD_PARTY you'll need to use
- * soup_cookie_jar_set_cookie_with_first_party(), otherwise the jar
+ * [method@CookieJar.set_cookie_with_first_party], otherwise the jar
  * will have no way of knowing if the cookie is being set by a third
  * party or not.
- *
  **/
 void
 soup_cookie_jar_set_cookie (SoupCookieJar *jar, GUri *uri,
@@ -754,10 +756,10 @@ soup_cookie_jar_set_cookie (SoupCookieJar *jar, GUri *uri,
  * @cookie: the stringified cookie to set
  *
  * Adds @cookie to @jar, exactly as though it had appeared in a
- * Set-Cookie header returned from a request to @uri. @first_party
- * will be used to reject cookies coming from third party resources in
- * case such a security policy is set in the @jar.
+ * Set-Cookie header returned from a request to @uri.
  *
+ * @first_party will be used to reject cookies coming from third party resources
+ * in case such a security policy is set in the @jar.
  **/
 void
 soup_cookie_jar_set_cookie_with_first_party (SoupCookieJar *jar,
@@ -860,13 +862,13 @@ soup_cookie_jar_session_feature_init (SoupSessionFeatureInterface *feature_inter
  * soup_cookie_jar_all_cookies:
  * @jar: a #SoupCookieJar
  *
- * Constructs a #GSList with every cookie inside the @jar.
+ * Constructs a [struct@GLib.List] with every cookie inside the @jar.
+ *
  * The cookies in the list are a copy of the original, so
  * you have to free them when you are done with them.
  *
  * Returns: (transfer full) (element-type Soup.Cookie): a #GSList
- * with all the cookies in the @jar.
- *
+ *   with all the cookies in the @jar.
  **/
 GSList *
 soup_cookie_jar_all_cookies (SoupCookieJar *jar)
@@ -896,8 +898,9 @@ soup_cookie_jar_all_cookies (SoupCookieJar *jar)
  * @jar: a #SoupCookieJar
  * @cookie: a #SoupCookie
  *
- * Deletes @cookie from @jar, emitting the 'changed' signal.
+ * Deletes @cookie from @jar.
  *
+ * Emits the [signal@CookieJar::changed] signal.
  **/
 void
 soup_cookie_jar_delete_cookie (SoupCookieJar *jar,
@@ -933,44 +936,42 @@ soup_cookie_jar_delete_cookie (SoupCookieJar *jar,
  * SoupCookieJarAcceptPolicy:
  * @SOUP_COOKIE_JAR_ACCEPT_ALWAYS: accept all cookies unconditionally.
  * @SOUP_COOKIE_JAR_ACCEPT_NEVER: reject all cookies unconditionally.
- * @SOUP_COOKIE_JAR_ACCEPT_NO_THIRD_PARTY: accept all cookies set by
- * the main document loaded in the application using libsoup. An
- * example of the most common case, web browsers, would be: If
- * http://www.example.com is the page loaded, accept all cookies set
- * by example.com, but if a resource from http://www.third-party.com
- * is loaded from that page reject any cookie that it could try to
- * set. For libsoup to be able to tell apart first party cookies from
- * the rest, the application must call soup_message_set_first_party()
- * on each outgoing #SoupMessage, setting the #GUri of the main
- * 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.
- * @SOUP_COOKIE_JAR_ACCEPT_GRANDFATHERED_THIRD_PARTY: accept all cookies
- * set by the main document loaded in the application using libsoup, and
- * from domains that have previously set at least one cookie when loaded
- * as the main document. An example of the most common case, web browsers,
- * would be: if http://www.example.com is the page loaded, accept all
- * cookies set by example.com, but if a resource from http://www.third-party.com
- * is loaded from that page, reject any cookie that it could try to
- * set unless it already has a cookie in the cookie jar. For libsoup to
- * be able to tell apart first party cookies from the rest, the
- * application must call soup_message_set_first_party() on each outgoing
- * #SoupMessage, setting the #GUri of the main 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.
+ * @SOUP_COOKIE_JAR_ACCEPT_NO_THIRD_PARTY: accept all cookies set by the main
+ *   document loaded in the application using libsoup. An example of the most
+ *   common case, web browsers, would be: If http://www.example.com is the page
+ *   loaded, accept all cookies set by example.com, but if a resource from
+ *   http://www.third-party.com is loaded from that page reject any cookie that
+ *   it could try to set. For libsoup to be able to tell apart first party
+ *   cookies from the rest, the application must call
+ *   [method@Message.set_first_party] on each outgoing [class@Message], setting
+ *   the [struct@GLib.Uri] of the main 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.
+ * @SOUP_COOKIE_JAR_ACCEPT_GRANDFATHERED_THIRD_PARTY: accept all cookies set by
+ *   the main document loaded in the application using libsoup, and from domains
+ *   that have previously set at least one cookie when loaded as the main
+ *   document. An example of the most common case, web browsers, would be: if
+ *   http://www.example.com is the page loaded, accept all cookies set by
+ *   example.com, but if a resource from http://www.third-party.com is loaded
+ *   from that page, reject any cookie that it could try to set unless it
+ *   already has a cookie in the cookie jar. For libsoup to be able to tell
+ *   apart first party cookies from the rest, the application must call
+ *   [method@Message.set_first_party] on each outgoing #SoupMessage, setting the
+ *   [struct@GLib.Uri] of the main 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.
- *
  */
 
 /**
- * soup_cookie_jar_get_accept_policy:
+ * soup_cookie_jar_get_accept_policy: (attributes org.gtk.Method.get_property=accept-policy)
  * @jar: a #SoupCookieJar
  *
- * Gets @jar's #SoupCookieJarAcceptPolicy
+ * Gets @jar's [enum@CookieJarAcceptPolicy].
  *
  * Returns: the #SoupCookieJarAcceptPolicy set in the @jar
- *
  **/
 SoupCookieJarAcceptPolicy
 soup_cookie_jar_get_accept_policy (SoupCookieJar *jar)
@@ -984,12 +985,11 @@ soup_cookie_jar_get_accept_policy (SoupCookieJar *jar)
 }
 
 /**
- * soup_cookie_jar_set_accept_policy:
+ * soup_cookie_jar_set_accept_policy: (attributes org.gtk.Method.set_property=accept-policy)
  * @jar: a #SoupCookieJar
  * @policy: a #SoupCookieJarAcceptPolicy
  * 
  * Sets @policy as the cookie acceptance policy for @jar.
- *
  **/
 void
 soup_cookie_jar_set_accept_policy (SoupCookieJar *jar,
@@ -1014,7 +1014,6 @@ soup_cookie_jar_set_accept_policy (SoupCookieJar *jar,
  * Gets whether @jar stores cookies persistenly.
  *
  * Returns: %TRUE if @jar storage is persistent or %FALSE otherwise.
- *
  **/
 gboolean
 soup_cookie_jar_is_persistent (SoupCookieJar *jar)
diff --git a/libsoup/cookies/soup-cookie.c b/libsoup/cookies/soup-cookie.c
index 021d527d..52310ed5 100644
--- a/libsoup/cookies/soup-cookie.c
+++ b/libsoup/cookies/soup-cookie.c
@@ -20,21 +20,13 @@
 #include "soup.h"
 
 /**
- * SECTION:soup-cookie
- * @short_description: HTTP Cookies
- * @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.
- **/
-
-/**
  * SoupCookie:
  *
- * An HTTP cookie.
+ * Implements HTTP cookies, as described by
+ * [RFC 6265](http://tools.ietf.org/html/rfc6265.txt).
+ *
+ * To have a [class@Session] handle cookies for your appliction
+ * automatically, use a [class@CookieJar].
  *
  * @name and @value will be set for all cookies. If the cookie is
  * generated from a string that appears to have no name, then @name
@@ -54,7 +46,6 @@
  * If @http_only is set, the cookie should not be exposed to untrusted
  * code (eg, javascript), so as to minimize the danger posed by
  * cross-site scripting attacks.
- *
  **/
 
 struct _SoupCookie {
@@ -76,7 +67,6 @@ G_DEFINE_BOXED_TYPE (SoupCookie, soup_cookie, soup_cookie_copy, soup_cookie_free
  * Copies @cookie.
  *
  * Returns: a copy of @cookie
- *
  **/
 SoupCookie *
 soup_cookie_copy (SoupCookie *cookie)
@@ -101,12 +91,12 @@ soup_cookie_copy (SoupCookie *cookie)
  * @cookie: a #SoupCookie
  * @host: a URI
  *
- * Checks if the @cookie's domain and @host match in the sense that
- * @cookie should be sent when making a request to @host, or that
- * @cookie should be accepted when receiving a response from @host.
+ * Checks if the @cookie's domain and @host match.
+ *
+ * The domains match if @cookie should be sent when making a request to @host,
+ * or that @cookie should be accepted when receiving a response from @host.
  * 
  * Returns: %TRUE if the domains match, %FALSE otherwise
- *
  **/
 gboolean
 soup_cookie_domain_matches (SoupCookie *cookie, const char *host)
@@ -349,9 +339,10 @@ cookie_new_internal (const char *name, const char *value,
  * @path: cookie path, or %NULL
  * @max_age: max age of the cookie, or -1 for a session cookie
  *
- * Creates a new #SoupCookie with the given attributes. (Use
- * soup_cookie_set_secure() and soup_cookie_set_http_only() if you
- * need to set those attributes on the returned cookie.)
+ * Creates a new #SoupCookie with the given attributes.
+ *
+ * Use [method@Cookie.set_secure] and [method@Cookie.set_http_only] if you
+ * need to set those attributes on the returned cookie.
  *
  * If @domain starts with ".", that indicates a domain (which matches
  * the string after the ".", or any hostname that has @domain as a
@@ -365,10 +356,9 @@ cookie_new_internal (const char *name, const char *value,
  * %SOUP_COOKIE_MAX_AGE_ONE_WEEK and %SOUP_COOKIE_MAX_AGE_ONE_YEAR (or
  * multiples thereof) to calculate this value. (If you really care
  * about setting the exact time that the cookie will expire, use
- * soup_cookie_set_expires().)
+ * [method@Cookie.set_expires].)
  *
  * Returns: a new #SoupCookie.
- *
  **/
 SoupCookie *
 soup_cookie_new (const char *name, const char *value,
@@ -393,10 +383,11 @@ soup_cookie_new (const char *name, const char *value,
 /**
  * soup_cookie_parse:
  * @header: a cookie string (eg, the value of a Set-Cookie header)
- * @origin: (nullable): origin of the cookie, or %NULL
+ * @origin: (nullable): origin of the cookie
+ *
+ * Parses @header and returns a #SoupCookie.
  *
- * Parses @header and returns a #SoupCookie. (If @header contains
- * multiple cookies, only the first one will be parsed.)
+ * If @header contains multiple cookies, only the first one will be parsed.
  *
  * If @header does not have "path" or "domain" attributes, they will
  * be defaulted from @origin. If @origin is %NULL, path will default
@@ -406,9 +397,8 @@ soup_cookie_new (const char *name, const char *value,
  * of the cookie.
  *
  * Returns: (nullable): a new #SoupCookie, or %NULL if it could
- * not be parsed, or contained an illegal "domain" attribute for a
- * cookie originating from @origin.
- *
+ *   not be parsed, or contained an illegal "domain" attribute for a
+ *   cookie originating from @origin.
  **/
 SoupCookie *
 soup_cookie_parse (const char *cookie, GUri *origin)
@@ -423,10 +413,9 @@ soup_cookie_parse (const char *cookie, GUri *origin)
  * soup_cookie_get_name:
  * @cookie: a #SoupCookie
  *
- * Gets @cookie's name
+ * Gets @cookie's name.
  *
  * Returns: @cookie's name
- *
  **/
 const char *
 soup_cookie_get_name (SoupCookie *cookie)
@@ -439,8 +428,7 @@ soup_cookie_get_name (SoupCookie *cookie)
  * @cookie: a #SoupCookie
  * @name: the new name
  *
- * Sets @cookie's name to @name
- *
+ * Sets @cookie's name to @name.
  **/
 void
 soup_cookie_set_name (SoupCookie *cookie, const char *name)
@@ -453,10 +441,9 @@ soup_cookie_set_name (SoupCookie *cookie, const char *name)
  * soup_cookie_get_value:
  * @cookie: a #SoupCookie
  *
- * Gets @cookie's value
+ * Gets @cookie's value.
  *
  * Returns: @cookie's value
- *
  **/
 const char *
 soup_cookie_get_value (SoupCookie *cookie)
@@ -469,8 +456,7 @@ soup_cookie_get_value (SoupCookie *cookie)
  * @cookie: a #SoupCookie
  * @value: the new value
  *
- * Sets @cookie's value to @value
- *
+ * Sets @cookie's value to @value.
  **/
 void
 soup_cookie_set_value (SoupCookie *cookie, const char *value)
@@ -483,10 +469,9 @@ soup_cookie_set_value (SoupCookie *cookie, const char *value)
  * soup_cookie_get_domain:
  * @cookie: a #SoupCookie
  *
- * Gets @cookie's domain
+ * Gets @cookie's domain.
  *
  * Returns: @cookie's domain
- *
  **/
 const char *
 soup_cookie_get_domain (SoupCookie *cookie)
@@ -499,8 +484,7 @@ soup_cookie_get_domain (SoupCookie *cookie)
  * @cookie: a #SoupCookie
  * @domain: the new domain
  *
- * Sets @cookie's domain to @domain
- *
+ * Sets @cookie's domain to @domain.
  **/
 void
 soup_cookie_set_domain (SoupCookie *cookie, const char *domain)
@@ -513,10 +497,9 @@ soup_cookie_set_domain (SoupCookie *cookie, const char *domain)
  * soup_cookie_get_path:
  * @cookie: a #SoupCookie
  *
- * Gets @cookie's path
+ * Gets @cookie's path.
  *
  * Returns: @cookie's path
- *
  **/
 const char *
 soup_cookie_get_path (SoupCookie *cookie)
@@ -529,8 +512,7 @@ soup_cookie_get_path (SoupCookie *cookie)
  * @cookie: a #SoupCookie
  * @path: the new path
  *
- * Sets @cookie's path to @path
- *
+ * Sets @cookie's path to @path.
  **/
 void
 soup_cookie_set_path (SoupCookie *cookie, const char *path)
@@ -544,17 +526,17 @@ soup_cookie_set_path (SoupCookie *cookie, const char *path)
  * @cookie: a #SoupCookie
  * @max_age: the new max age
  *
- * Sets @cookie's max age to @max_age. If @max_age is -1, the cookie
- * is a session cookie, and will expire at the end of the client's
- * session. Otherwise, it is the number of seconds until the cookie
- * expires. You can use the constants %SOUP_COOKIE_MAX_AGE_ONE_HOUR,
- * %SOUP_COOKIE_MAX_AGE_ONE_DAY, %SOUP_COOKIE_MAX_AGE_ONE_WEEK and
- * %SOUP_COOKIE_MAX_AGE_ONE_YEAR (or multiples thereof) to calculate
- * this value. (A value of 0 indicates that the cookie should be
- * considered already-expired.)
+ * Sets @cookie's max age to @max_age.
  *
- * (This sets the same property as soup_cookie_set_expires().)
+ * If @max_age is -1, the cookie is a session cookie, and will expire at the end
+ * of the client's session. Otherwise, it is the number of seconds until the
+ * cookie expires. You can use the constants %SOUP_COOKIE_MAX_AGE_ONE_HOUR,
+ * %SOUP_COOKIE_MAX_AGE_ONE_DAY, %SOUP_COOKIE_MAX_AGE_ONE_WEEK and
+ * %SOUP_COOKIE_MAX_AGE_ONE_YEAR (or multiples thereof) to calculate this value.
+ * (A value of 0 indicates that the cookie should be considered
+ * already-expired.)
  *
+ * This sets the same property as [method@Cookie.set_expires].
  **/
 void
 soup_cookie_set_max_age (SoupCookie *cookie, int max_age)
@@ -579,30 +561,30 @@ soup_cookie_set_max_age (SoupCookie *cookie, int max_age)
 /**
  * SOUP_COOKIE_MAX_AGE_ONE_HOUR:
  *
- * A constant corresponding to 1 hour, for use with soup_cookie_new()
- * and soup_cookie_set_max_age().
+ * A constant corresponding to 1 hour.
  *
+ * For use with [ctor@Cookie.new] and [method@Cookie.set_max_age].
  **/
 /**
  * SOUP_COOKIE_MAX_AGE_ONE_DAY:
  *
- * A constant corresponding to 1 day, for use with soup_cookie_new()
- * and soup_cookie_set_max_age().
+ * A constant corresponding to 1 day.
  *
+ * For use with [ctor@Cookie.new] and [method@Cookie.set_max_age].
  **/
 /**
  * SOUP_COOKIE_MAX_AGE_ONE_WEEK:
  *
- * A constant corresponding to 1 week, for use with soup_cookie_new()
- * and soup_cookie_set_max_age().
+ * A constant corresponding to 1 week.
  *
+ * For use with [ctor@Cookie.new] and [method@Cookie.set_max_age].
  **/
 /**
  * SOUP_COOKIE_MAX_AGE_ONE_YEAR:
  *
- * A constant corresponding to 1 year, for use with soup_cookie_new()
- * and soup_cookie_set_max_age().
+ * A constant corresponding to 1 year.
  *
+ * For use with [ctor@Cookie.new] and [method@Cookie.set_max_age].
  **/
 
 /**
@@ -611,10 +593,8 @@ soup_cookie_set_max_age (SoupCookie *cookie, int max_age)
  *
  * Gets @cookie's expiration time.
  *
- * Returns: (nullable) (transfer none): @cookie's expiration
- * time, which is owned by @cookie and should not be modified or
- * freed.
- *
+ * Returns: (nullable) (transfer none): @cookie's expiration time, which is
+ *   owned by @cookie and should not be modified or freed.
  **/
 GDateTime *
 soup_cookie_get_expires (SoupCookie *cookie)
@@ -627,12 +607,12 @@ soup_cookie_get_expires (SoupCookie *cookie)
  * @cookie: a #SoupCookie
  * @expires: the new expiration time, or %NULL
  *
- * Sets @cookie's expiration time to @expires. If @expires is %NULL,
- * @cookie will be a session cookie and will expire at the end of the
- * client's session.
+ * Sets @cookie's expiration time to @expires.
  *
- * (This sets the same property as soup_cookie_set_max_age().)
+ * If @expires is %NULL, @cookie will be a session cookie and will expire at the
+ * end of the client's session.
  *
+ * (This sets the same property as [method@Cookie.set_max_age].)
  **/
 void
 soup_cookie_set_expires (SoupCookie *cookie, GDateTime *expires)
@@ -650,10 +630,9 @@ soup_cookie_set_expires (SoupCookie *cookie, GDateTime *expires)
  * soup_cookie_get_secure:
  * @cookie: a #SoupCookie
  *
- * Gets @cookie's secure attribute
+ * Gets @cookie's secure attribute.
  *
  * Returns: @cookie's secure attribute
- *
  **/
 gboolean
 soup_cookie_get_secure (SoupCookie *cookie)
@@ -666,10 +645,10 @@ soup_cookie_get_secure (SoupCookie *cookie)
  * @cookie: a #SoupCookie
  * @secure: the new value for the secure attribute
  *
- * Sets @cookie's secure attribute to @secure. If %TRUE, @cookie will
- * only be transmitted from the client to the server over secure
- * (https) connections.
+ * Sets @cookie's secure attribute to @secure.
  *
+ * If %TRUE, @cookie will only be transmitted from the client to the server over
+ * secure (https) connections.
  **/
 void
 soup_cookie_set_secure (SoupCookie *cookie, gboolean secure)
@@ -681,10 +660,9 @@ soup_cookie_set_secure (SoupCookie *cookie, gboolean secure)
  * soup_cookie_get_http_only:
  * @cookie: a #SoupCookie
  *
- * Gets @cookie's HttpOnly attribute
+ * Gets @cookie's HttpOnly attribute.
  *
  * Returns: @cookie's HttpOnly attribute
- *
  **/
 gboolean
 soup_cookie_get_http_only (SoupCookie *cookie)
@@ -697,10 +675,10 @@ soup_cookie_get_http_only (SoupCookie *cookie)
  * @cookie: a #SoupCookie
  * @http_only: the new value for the HttpOnly attribute
  *
- * Sets @cookie's HttpOnly attribute to @http_only. If %TRUE, @cookie
- * will be marked as "http only", meaning it should not be exposed to
- * web page scripts or other untrusted code.
+ * Sets @cookie's HttpOnly attribute to @http_only.
  *
+ * If %TRUE, @cookie will be marked as "http only", meaning it should not be
+ * exposed to web page scripts or other untrusted code.
  **/
 void
 soup_cookie_set_http_only (SoupCookie *cookie, gboolean http_only)
@@ -772,9 +750,9 @@ G_DEFINE_QUARK (soup-same-site-policy, soup_same_site_policy)
  * @cookie: a #SoupCookie
  * @policy: a #SoupSameSitePolicy
  *
- * When used in conjunction with soup_cookie_jar_get_cookie_list_with_same_site_info() this
- * sets the policy of when this cookie should be exposed.
- *
+ * When used in conjunction with
+ * [method@CookieJar.get_cookie_list_with_same_site_info] this sets the policy
+ * of when this cookie should be exposed.
  **/
 void
 soup_cookie_set_same_site_policy (SoupCookie         *cookie,
@@ -798,7 +776,6 @@ soup_cookie_set_same_site_policy (SoupCookie         *cookie,
  * Returns the same-site policy for this cookie.
  *
  * Returns: a #SoupSameSitePolicy
- *
  **/
 SoupSameSitePolicy
 soup_cookie_get_same_site_policy (SoupCookie *cookie)
@@ -810,11 +787,11 @@ soup_cookie_get_same_site_policy (SoupCookie *cookie)
  * soup_cookie_to_set_cookie_header:
  * @cookie: a #SoupCookie
  *
- * Serializes @cookie in the format used by the Set-Cookie header
- * (ie, for sending a cookie from a #SoupServer to a client).
+ * Serializes @cookie in the format used by the Set-Cookie header.
  *
- * Returns: the header
+ * i.e. for sending a cookie from a [class@Server] to a client.
  *
+ * Returns: the header
  **/
 char *
 soup_cookie_to_set_cookie_header (SoupCookie *cookie)
@@ -830,10 +807,9 @@ soup_cookie_to_set_cookie_header (SoupCookie *cookie)
  * @cookie: a #SoupCookie
  *
  * Serializes @cookie in the format used by the Cookie header (ie, for
- * returning a cookie from a #SoupSession to a server).
+ * returning a cookie from a [class@Session] to a server).
  *
  * Returns: the header
- *
  **/
 char *
 soup_cookie_to_cookie_header (SoupCookie *cookie)
@@ -848,8 +824,7 @@ soup_cookie_to_cookie_header (SoupCookie *cookie)
  * soup_cookie_free:
  * @cookie: a #SoupCookie
  *
- * Frees @cookie
- *
+ * Frees @cookie.
  **/
 void
 soup_cookie_free (SoupCookie *cookie)
@@ -870,14 +845,14 @@ soup_cookie_free (SoupCookie *cookie)
  * soup_cookies_from_response:
  * @msg: a #SoupMessage containing a "Set-Cookie" response header
  *
- * Parses @msg's Set-Cookie response headers and returns a #GSList of
- * #SoupCookie<!-- -->s. Cookies that do not specify "path" or
- * "domain" attributes will have their values defaulted from @msg.
+ * Parses @msg's Set-Cookie response headers and returns a [struct@GLib.SList]
+ * of `SoupCookie`s.
  *
- * Returns: (element-type SoupCookie) (transfer full): a #GSList
- * of #SoupCookie<!-- -->s, which can be freed with
- * soup_cookies_free().
+ * Cookies that do not specify "path" or "domain" attributes will have their
+ * values defaulted from @msg.
  *
+ * Returns: (element-type SoupCookie) (transfer full): a #GSList of
+ *   `SoupCookie`s, which can be freed with [method@Cookie.free].
  **/
 GSList *
 soup_cookies_from_response (SoupMessage *msg)
@@ -910,17 +885,16 @@ soup_cookies_from_response (SoupMessage *msg)
  * soup_cookies_from_request:
  * @msg: a #SoupMessage containing a "Cookie" request header
  *
- * Parses @msg's Cookie request header and returns a #GSList of
- * #SoupCookie<!-- -->s. As the "Cookie" header, unlike "Set-Cookie",
- * only contains cookie names and values, none of the other
- * #SoupCookie fields will be filled in. (Thus, you can't generally
- * pass a cookie returned from this method directly to
- * soup_cookies_to_response().)
+ * Parses @msg's Cookie request header and returns a [struct@GLib.SList] of
+ * `SoupCookie`s.
  *
- * Returns: (element-type SoupCookie) (transfer full): a #GSList
- * of #SoupCookie<!-- -->s, which can be freed with
- * soup_cookies_free().
+ * As the "Cookie" header, unlike "Set-Cookie", only contains cookie names and
+ * values, none of the other #SoupCookie fields will be filled in. (Thus, you
+ * can't generally pass a cookie returned from this method directly to
+ * [func@cookies_to_response].)
  *
+ * Returns: (element-type SoupCookie) (transfer full): a #GSList of
+ *   `SoupCookie`s, which can be freed with [method@Cookie.free].
  **/
 GSList *
 soup_cookies_from_request (SoupMessage *msg)
@@ -956,9 +930,10 @@ soup_cookies_from_request (SoupMessage *msg)
  * @msg: a #SoupMessage
  *
  * Appends a "Set-Cookie" response header to @msg for each cookie in
- * @cookies. (This is in addition to any other "Set-Cookie" headers
- * @msg may already have.)
+ * @cookies.
  *
+ * This is in addition to any other "Set-Cookie" headers
+ * @msg may already have.
  **/
 void
 soup_cookies_to_response (GSList *cookies, SoupMessage *msg)
@@ -982,11 +957,11 @@ soup_cookies_to_response (GSList *cookies, SoupMessage *msg)
  * @msg: a #SoupMessage
  *
  * Adds the name and value of each cookie in @cookies to @msg's
- * "Cookie" request. (If @msg already has a "Cookie" request header,
- * these cookies will be appended to the cookies already present. Be
- * careful that you do not append the same cookies twice, eg, when
- * requeuing a message.)
+ * "Cookie" request.
  *
+ * If @msg already has a "Cookie" request header, these cookies will be appended
+ * to the cookies already present. Be careful that you do not append the same
+ * cookies twice, eg, when requeuing a message.
  **/
 void
 soup_cookies_to_request (GSList *cookies, SoupMessage *msg)
@@ -1009,7 +984,6 @@ soup_cookies_to_request (GSList *cookies, SoupMessage *msg)
  * @cookies: (element-type SoupCookie): a #GSList of #SoupCookie
  *
  * Frees @cookies.
- *
  **/
 void
 soup_cookies_free (GSList *cookies)
@@ -1021,11 +995,10 @@ soup_cookies_free (GSList *cookies)
  * soup_cookies_to_cookie_header:
  * @cookies: (element-type SoupCookie): a #GSList of #SoupCookie
  *
- * Serializes a #GSList of #SoupCookie into a string suitable for
+ * Serializes a [struct@GLib.SList] of #SoupCookie into a string suitable for
  * setting as the value of the "Cookie" header.
  *
  * Returns: the serialization of @cookies
- *
  **/
 char *
 soup_cookies_to_cookie_header (GSList *cookies)
@@ -1054,9 +1027,7 @@ soup_cookies_to_cookie_header (GSList *cookies)
  * @uri, because it assumes that the caller has already done that.
  * But don't rely on that; it may change in the future.)
  *
- * Returns: %TRUE if @cookie should be sent to @uri, %FALSE if
- * not
- *
+ * Returns: %TRUE if @cookie should be sent to @uri, %FALSE if not
  **/
 gboolean
 soup_cookie_applies_to_uri (SoupCookie *cookie, GUri *uri)
@@ -1100,7 +1071,6 @@ soup_cookie_applies_to_uri (SoupCookie *cookie, GUri *uri)
  * match. This may change in the future.
  *
  * Returns: whether the cookies are equal.
- *
  */
 gboolean
 soup_cookie_equal (SoupCookie *cookie1, SoupCookie *cookie2)
diff --git a/libsoup/hsts/soup-hsts-enforcer-db.c b/libsoup/hsts/soup-hsts-enforcer-db.c
index 9c8ff1be..cb630b18 100644
--- a/libsoup/hsts/soup-hsts-enforcer-db.c
+++ b/libsoup/hsts/soup-hsts-enforcer-db.c
@@ -19,19 +19,14 @@
 #include "soup.h"
 
 /**
- * SECTION:soup-hsts-enforcer-db
- * @short_description: Persistent HTTP Strict Transport Security enforcer
+ * SoupHSTSEnforcerDB:
+ *
+ * Persistent HTTP Strict Transport Security enforcer.
  *
- * #SoupHSTSEnforcerDB is a #SoupHSTSEnforcer that uses a SQLite
+ * #SoupHSTSEnforcerDB is a [class@HSTSEnforcer] that uses a SQLite
  * database as a backend for persistency.
  **/
 
-/**
- * SoupHSTSEnforcerDB:
- *
- * Subclass of #SoupHSTSEnforcer using an sqlite database.
- */
-
 enum {
 	PROP_0,
 
@@ -116,10 +111,9 @@ soup_hsts_enforcer_db_get_property (GObject *object, guint prop_id,
  * policies. If the file doesn't exist, a new database will be created
  * and initialized. Changes to the policies during the lifetime of a
  * #SoupHSTSEnforcerDB will be written to @filename when
- * #SoupHSTSEnforcer::changed is emitted.
+ * [signal@HSTSEnforcer::changed] is emitted.
  *
  * Returns: the new #SoupHSTSEnforcer
- *
  **/
 SoupHSTSEnforcer *
 soup_hsts_enforcer_db_new (const char *filename)
diff --git a/libsoup/hsts/soup-hsts-enforcer.c b/libsoup/hsts/soup-hsts-enforcer.c
index b4954542..5628028d 100644
--- a/libsoup/hsts/soup-hsts-enforcer.c
+++ b/libsoup/hsts/soup-hsts-enforcer.c
@@ -19,39 +19,32 @@
 #include "soup-uri-utils-private.h"
 
 /**
- * SECTION:soup-hsts-enforcer
- * @short_description: Automatic HTTP Strict Transport Security enforcing
- * for #SoupSession
+ * SoupHSTSEnforcer:
+ *
+ * Automatic HTTP Strict Transport Security enforcing for [class@Session].
  *
  * A #SoupHSTSEnforcer stores HSTS policies and enforces them when
- * required. #SoupHSTSEnforcer implements #SoupSessionFeature, so you
+ * required. #SoupHSTSEnforcer implements [iface@SessionFeature], so you
  * can add an HSTS enforcer to a session with
- * soup_session_add_feature() or soup_session_add_feature_by_type().
+ * [method@Session.add_feature] or [method@Session.add_feature_by_type].
  *
  * #SoupHSTSEnforcer keeps track of all the HTTPS destinations that,
  * when connected to, return the Strict-Transport-Security header with
  * valid values. #SoupHSTSEnforcer will forget those destinations
  * upon expiry or when the server requests it.
  *
- * When the #SoupSession the #SoupHSTSEnforcer is attached to queues
- * or restarts a message, the #SoupHSTSEnforcer will rewrite the URI
- * to HTTPS if the destination is a known HSTS host and is contacted
- * over an insecure transport protocol (HTTP). Users of
- * #SoupHSTSEnforcer are advised to listen to changes in
- * SoupMessage:uri in order to be aware of changes in the message URI.
+ * When the [class@Session] the #SoupHSTSEnforcer is attached to queues or
+ * restarts a message, the #SoupHSTSEnforcer will rewrite the URI to HTTPS if
+ * the destination is a known HSTS host and is contacted over an insecure
+ * transport protocol (HTTP). Users of #SoupHSTSEnforcer are advised to listen
+ * to changes in the [property@Message:uri] property 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 #SoupHSTSEnforcerDB for a persistent
+ * HSTS policy persistence. See [class@HSTSEnforcerDB] for a persistent
  * enforcer.
- *
  **/
 
-/**
- * SoupHSTSEnforcer:
- *
- * Class for storing and enforcing a #SoupHSTSPolicy.
- */
-
 static void soup_hsts_enforcer_session_feature_init (SoupSessionFeatureInterface *feature_interface, gpointer interface_data);
 
 enum {
@@ -160,7 +153,9 @@ soup_hsts_enforcer_class_init (SoupHSTSEnforcerClass *hsts_enforcer_class)
 	 * @old_policy: the old #SoupHSTSPolicy value
 	 * @new_policy: the new #SoupHSTSPolicy value
 	 *
-	 * Emitted when @hsts_enforcer changes. If a policy has been added,
+	 * Emitted when @hsts_enforcer changes.
+	 *
+	 * If a policy has been added,
 	 * @new_policy will contain the newly-added policy and
 	 * @old_policy will be %NULL. If a policy has been deleted,
 	 * @old_policy will contain the to-be-deleted policy and
@@ -186,12 +181,12 @@ soup_hsts_enforcer_class_init (SoupHSTSEnforcerClass *hsts_enforcer_class)
 /**
  * soup_hsts_enforcer_new:
  *
- * Creates a new #SoupHSTSEnforcer. The base #SoupHSTSEnforcer class
- * does not support persistent storage of HSTS policies, see
- * #SoupHSTSEnforcerDB for that.
+ * Creates a new #SoupHSTSEnforcer.
  *
- * Returns: a new #SoupHSTSEnforcer
+ * The base #SoupHSTSEnforcer class does not support persistent storage of HSTS
+ * policies, see [class@HSTSEnforcerDB] for that.
  *
+ * Returns: a new #SoupHSTSEnforcer
  **/
 SoupHSTSEnforcer *
 soup_hsts_enforcer_new (void)
@@ -317,14 +312,14 @@ soup_hsts_enforcer_insert_policy (SoupHSTSEnforcer *hsts_enforcer,
  * @hsts_enforcer: a #SoupHSTSEnforcer
  * @policy: (transfer none): the policy of the HSTS host
  *
- * Sets @policy to @hsts_enforcer. If @policy is expired, any
- * existing HSTS policy for its host will be removed instead. If a
- * policy existed for this host, it will be replaced. Otherwise, the
- * new policy will be inserted. If the policy is a session policy, that
- * is, one created with soup_hsts_policy_new_session_policy(), the policy
- * will not expire and will be enforced during the lifetime of
- * @hsts_enforcer's #SoupSession.
+ * Sets @policy to @hsts_enforcer.
  *
+ * If @policy is expired, any existing HSTS policy for its host will be removed
+ * instead. If a policy existed for this host, it will be replaced. Otherwise,
+ * the new policy will be inserted. If the policy is a session policy, that is,
+ * one created with [ctor@HSTSPolicy.new_session_policy], the policy will not
+ * expire and will be enforced during the lifetime of @hsts_enforcer's
+ * [class@Session].
  **/
 void
 soup_hsts_enforcer_set_policy (SoupHSTSEnforcer *hsts_enforcer,
@@ -365,10 +360,10 @@ soup_hsts_enforcer_set_policy (SoupHSTSEnforcer *hsts_enforcer,
  * @domain: policy domain or hostname
  * @include_subdomains: %TRUE if the policy applies on sub domains
  *
- * Sets a session policy for @domain. A session policy is a policy
- * that is permanent to the lifetime of @hsts_enforcer's #SoupSession
- * and doesn't expire.
+ * Sets a session policy for @domain.
  *
+ * A session policy is a policy that is permanent to the lifetime of
+ * @hsts_enforcer's [class@Session] and doesn't expire.
  **/
 void
 soup_hsts_enforcer_set_session_policy (SoupHSTSEnforcer *hsts_enforcer,
@@ -581,7 +576,6 @@ soup_hsts_enforcer_session_feature_init (SoupSessionFeatureInterface *feature_in
  * Gets whether @hsts_enforcer stores policies persistenly.
  *
  * Returns: %TRUE if @hsts_enforcer storage is persistent or %FALSE otherwise.
- *
  **/
 gboolean
 soup_hsts_enforcer_is_persistent (SoupHSTSEnforcer *hsts_enforcer)
@@ -599,8 +593,7 @@ soup_hsts_enforcer_is_persistent (SoupHSTSEnforcer *hsts_enforcer)
  * Gets whether @hsts_enforcer has a currently valid policy for @domain.
  *
  * Returns: %TRUE if access to @domain should happen over HTTPS, false
- * otherwise.
- *
+ *   otherwise.
  **/
 gboolean
 soup_hsts_enforcer_has_valid_policy (SoupHSTSEnforcer *hsts_enforcer,
@@ -641,10 +634,9 @@ add_domain_to_list (gpointer key,
  *
  * Gets a list of domains for which there are policies in @enforcer.
  *
- *
  * Returns: (element-type utf8) (transfer full): a newly allocated
- * list of domains. Use g_list_free_full() and g_free() to free the
- * list.
+ *   list of domains. Use [func@GLib.List.free_full] and [func@GLib.free] to free the
+ *   list.
  **/
 GList*
 soup_hsts_enforcer_get_domains (SoupHSTSEnforcer *hsts_enforcer,
@@ -679,10 +671,8 @@ add_policy_to_list (gpointer key,
  * Gets a list with the policies in @enforcer.
  *
  * Returns: (element-type SoupHSTSPolicy) (transfer full): a newly
- * allocated list of policies. Use g_list_free_full() and
- * soup_hsts_policy_free() to free the list.
- *
- *
+ *   allocated list of policies. Use [func@GLib.List.free_full] and
+ *   [method@HSTSPolicy.free] to free the list.
  **/
 GList*
 soup_hsts_enforcer_get_policies (SoupHSTSEnforcer *hsts_enforcer,
diff --git a/libsoup/hsts/soup-hsts-enforcer.h b/libsoup/hsts/soup-hsts-enforcer.h
index 309bdc84..08791311 100644
--- a/libsoup/hsts/soup-hsts-enforcer.h
+++ b/libsoup/hsts/soup-hsts-enforcer.h
@@ -18,7 +18,7 @@ G_DECLARE_DERIVABLE_TYPE (SoupHSTSEnforcer, soup_hsts_enforcer, SOUP, HSTS_ENFOR
  * SoupHSTSEnforcerClass:
  * @parent_class: The parent class.
  * @is_persistent: The @is_persistent function advertises whether the enforcer is persistent or
- * whether changes made to it will be lost when the underlying #SoupSession is finished.
+ * whether changes made to it will be lost when the underlying [class@Session] is finished.
  * @has_valid_policy: The @has_valid_policy function is called to check whether there is a valid
  * policy for the given domain. This method should return %TRUE for #SoupHSTSEnforcer to
  * change the scheme of the #GUri in the #SoupMessage to HTTPS. Implementations might want to
diff --git a/libsoup/hsts/soup-hsts-policy.c b/libsoup/hsts/soup-hsts-policy.c
index 38958732..7843481e 100644
--- a/libsoup/hsts/soup-hsts-policy.c
+++ b/libsoup/hsts/soup-hsts-policy.c
@@ -19,22 +19,13 @@
 #include "soup.h"
 
 /**
- * SECTION:soup-hsts-policy
- * @title: SoupHSTSPolicy
- * @short_description: HSTS policies
- *
- * Policies to be used with #SoupHSTSEnforcer.
- *
- */
-
-/**
  * SoupHSTSPolicy:
  *
  * #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
+ * must be IDNA-canonicalized. [ctor@HSTSPolicy.new] and related methods
  * will do this for you.
  *
  * @max_age contains the 'max-age' value from the Strict Transport
@@ -47,7 +38,6 @@
  *
  * If @include_subdomains is %TRUE, the Strict Transport Security policy
  * must also be enforced on subdomains of @domain.
- *
  **/
 
 struct _SoupHSTSPolicy {
@@ -66,7 +56,6 @@ G_DEFINE_BOXED_TYPE (SoupHSTSPolicy, soup_hsts_policy, soup_hsts_policy_copy, so
  * Copies @policy.
  *
  * Returns: (transfer full): a copy of @policy
- *
  **/
 SoupHSTSPolicy *
 soup_hsts_policy_copy (SoupHSTSPolicy *policy)
@@ -90,7 +79,6 @@ soup_hsts_policy_copy (SoupHSTSPolicy *policy)
  * Tests if @policy1 and @policy2 are equal.
  *
  * Returns: whether the policies are equal.
- *
  */
 gboolean
 soup_hsts_policy_equal (SoupHSTSPolicy *policy1, SoupHSTSPolicy *policy2)
@@ -141,14 +129,13 @@ is_hostname_valid (const char *hostname)
  * represented by this object must be enforced.
  *
  * @max_age is used to set the "expires" attribute on the policy; pass
- * SOUP_HSTS_POLICY_MAX_AGE_PAST for an already-expired policy, or a
+ * %SOUP_HSTS_POLICY_MAX_AGE_PAST for an already-expired policy, or a
  * lifetime in seconds.
  *
  * If @include_subdomains is %TRUE, the strict transport security policy
  * must also be enforced on all subdomains of @domain.
  *
  * Returns: a new #SoupHSTSPolicy.
- *
  **/
 SoupHSTSPolicy *
 soup_hsts_policy_new (const char *domain,
@@ -178,11 +165,12 @@ soup_hsts_policy_new (const char *domain,
  * @expires: the date of expiration of the policy or %NULL for a permanent policy
  * @include_subdomains: %TRUE if the policy applies on subdomains
  *
- * Full version of #soup_hsts_policy_new(), to use with an existing
- * expiration date. See #soup_hsts_policy_new() for details.
+ * Full version of [ctor@HSTSPolicy.new], to use with an existing
+ * expiration date.
  *
- * Returns: a new #SoupHSTSPolicy.
+ * See [ctor@HSTSPolicy.new] for details.
  *
+ * Returns: a new #SoupHSTSPolicy.
  **/
 SoupHSTSPolicy *
 soup_hsts_policy_new_full (const char *domain,
@@ -219,8 +207,9 @@ soup_hsts_policy_new_full (const char *domain,
  * @include_subdomains: %TRUE if the policy applies on sub domains
  *
  * Creates a new session #SoupHSTSPolicy with the given attributes.
+ *
  * A session policy is a policy that is valid during the lifetime of
- * the #SoupHSTSEnforcer it is added to. Contrary to regular policies,
+ * the [class@HSTSEnforcer] it is added to. Contrary to regular policies,
  * it has no expiration date and is not stored in persistent
  * enforcers. These policies are useful for user-agent to load their
  * own or user-defined rules.
@@ -232,7 +221,6 @@ soup_hsts_policy_new_full (const char *domain,
  * must also be enforced on all subdomains of @domain.
  *
  * Returns: a new #SoupHSTSPolicy.
- *
  **/
 SoupHSTSPolicy *
 soup_hsts_policy_new_session_policy (const char *domain,
@@ -253,8 +241,7 @@ soup_hsts_policy_new_session_policy (const char *domain,
  * returns a #SoupHSTSPolicy.
  *
  * Returns: (nullable): a new #SoupHSTSPolicy, or %NULL if no valid
- * "Strict-Transport-Security" response header was found.
- *
+ *   "Strict-Transport-Security" response header was found.
  **/
 SoupHSTSPolicy *
 soup_hsts_policy_new_from_response (SoupMessage *msg)
@@ -315,7 +302,6 @@ soup_hsts_policy_new_from_response (SoupMessage *msg)
  * Gets @policy's domain.
  *
  * Returns: (transfer none): @policy's domain.
- *
  **/
 const char *
 soup_hsts_policy_get_domain (SoupHSTSPolicy *policy)
@@ -329,11 +315,11 @@ soup_hsts_policy_get_domain (SoupHSTSPolicy *policy)
  * soup_hsts_policy_is_expired:
  * @policy: a #SoupHSTSPolicy
  *
- * Gets whether @policy is expired. Permanent policies never
- * expire.
+ * Gets whether @policy is expired.
  *
- * Returns: %TRUE if @policy is expired, %FALSE otherwise.
+ * Permanent policies never expire.
  *
+ * Returns: %TRUE if @policy is expired, %FALSE otherwise.
  **/
 gboolean
 soup_hsts_policy_is_expired (SoupHSTSPolicy *policy)
@@ -350,7 +336,6 @@ soup_hsts_policy_is_expired (SoupHSTSPolicy *policy)
  * Gets whether @policy include its subdomains.
  *
  * Returns: %TRUE if @policy includes subdomains, %FALSE otherwise.
- *
  **/
 gboolean
 soup_hsts_policy_includes_subdomains (SoupHSTSPolicy *policy)
@@ -365,10 +350,10 @@ soup_hsts_policy_includes_subdomains (SoupHSTSPolicy *policy)
  * @policy: a #SoupHSTSPolicy
  *
  * Gets whether @policy is a non-permanent, non-expirable session policy.
- * see soup_hsts_policy_new_session_policy() for details.
  *
- * Returns: %TRUE if @policy is permanent, %FALSE otherwise
+ * See [ctor@HSTSPolicy.new_session_policy] for details.
  *
+ * Returns: %TRUE if @policy is permanent, %FALSE otherwise
  **/
 gboolean
 soup_hsts_policy_is_session_policy (SoupHSTSPolicy *policy)
@@ -415,7 +400,6 @@ soup_hsts_policy_get_max_age (SoupHSTSPolicy *policy)
  * @policy: (transfer full): a #SoupHSTSPolicy
  *
  * Frees @policy.
- *
  **/
 void
 soup_hsts_policy_free (SoupHSTSPolicy *policy)
diff --git a/libsoup/server/soup-auth-domain-basic.c b/libsoup/server/soup-auth-domain-basic.c
index 24a3c22d..33de38a1 100644
--- a/libsoup/server/soup-auth-domain-basic.c
+++ b/libsoup/server/soup-auth-domain-basic.c
@@ -16,17 +16,12 @@
 #include "soup.h"
 
 /**
- * SECTION:soup-auth-domain-basic
- * @short_description: Server-side "Basic" authentication
+ * SoupAuthDomainBasic:
+ *
+ * Server-side "Basic" authentication.
  *
  * #SoupAuthDomainBasic handles the server side of HTTP "Basic" (ie,
  * cleartext password) authentication.
- **/
-
-/**
- * SoupAuthDomainBasic:
- *
- * Subclass of #SoupAuthDomain for Basic authentication.
  */
 
 enum {
@@ -118,9 +113,10 @@ soup_auth_domain_basic_get_property (GObject *object, guint prop_id,
  * @optname1: name of first option, or %NULL
  * @...: option name/value pairs
  *
- * Creates a #SoupAuthDomainBasic. You must set the
- * SoupAuthDomain:realm property, to indicate the realm name to be
- * returned with the authentication challenge to the client. Other
+ * Creates a #SoupAuthDomainBasic.
+ *
+ * You must set the [property@AuthDomain:realm] property, to indicate the realm
+ * name to be returned with the authentication challenge to the client. Other
  * parameters are optional.
  *
  * Returns: the new #SoupAuthDomain
@@ -147,9 +143,10 @@ soup_auth_domain_basic_new (const char *optname1, ...)
  * @msg: the message being authenticated
  * @username: the username provided by the client
  * @password: the password provided by the client
- * @user_data: the data passed to soup_auth_domain_basic_set_auth_callback()
+ * @user_data: the data passed to [method@AuthDomainBasic.set_auth_callback]
  *
  * Callback used by #SoupAuthDomainBasic for authentication purposes.
+ *
  * The application should verify that @username and @password and valid
  * and return %TRUE or %FALSE.
  *
@@ -168,22 +165,24 @@ soup_auth_domain_basic_new (const char *optname1, ...)
  **/
 
 /**
- * soup_auth_domain_basic_set_auth_callback:
+ * soup_auth_domain_basic_set_auth_callback: (attributes org.gtk.Method.set_property=auth-callback)
  * @domain: (type SoupAuthDomainBasic): the domain
  * @callback: the callback
  * @user_data: data to pass to @auth_callback
  * @dnotify: destroy notifier to free @user_data when @domain
- * is destroyed
+ *   is destroyed
  *
  * Sets the callback that @domain will use to authenticate incoming
- * requests. For each request containing authorization, @domain will
- * invoke the callback, and then either accept or reject the request
- * based on @callback's return value.
+ * requests.
+ *
+ * For each request containing authorization, @domain will invoke the callback,
+ * and then either accept or reject the request based on @callback's return
+ * value.
  *
  * You can also set the auth callback by setting the
- * SoupAuthDomainBasic:auth-callback and
- * SoupAuthDomainBasic:auth-data properties, which can also be
- * used to set the callback at construct time.
+ * [property@AuthDomainBasic:auth-callback] and
+ * [property@AuthDomainBasic:auth-data] properties, which can also be used to
+ * set the callback at construct time.
  **/
 void
 soup_auth_domain_basic_set_auth_callback (SoupAuthDomain *domain,
@@ -322,9 +321,9 @@ soup_auth_domain_basic_class_init (SoupAuthDomainBasicClass *basic_class)
 	object_class->get_property = soup_auth_domain_basic_get_property;
 
 	/**
-	 * SoupAuthDomainBasic:auth-callback: (type SoupAuthDomainBasicAuthCallback)
+	 * SoupAuthDomainBasic:auth-callback: (type SoupAuthDomainBasicAuthCallback) (attributes org.gtk.Property.set=soup_auth_domain_basic_set_auth_callback)
 	 *
-	 * The #SoupAuthDomainBasicAuthCallback
+	 * The [callback@AuthDomainBasicAuthCallback].
 	 */
         properties[PROP_AUTH_CALLBACK] =
 		g_param_spec_pointer ("auth-callback",
@@ -335,7 +334,7 @@ soup_auth_domain_basic_class_init (SoupAuthDomainBasicClass *basic_class)
 	/**
 	 * SoupAuthDomainBasic:auth-data:
 	 *
-	 * The data to pass to the #SoupAuthDomainBasicAuthCallback
+	 * The data to pass to the [callback@AuthDomainBasicAuthCallback].
 	 */
         properties[PROP_AUTH_DATA] =
 		g_param_spec_pointer ("auth-data",
diff --git a/libsoup/server/soup-auth-domain-digest.c b/libsoup/server/soup-auth-domain-digest.c
index 3a63bc4f..59d9f8f3 100644
--- a/libsoup/server/soup-auth-domain-digest.c
+++ b/libsoup/server/soup-auth-domain-digest.c
@@ -19,17 +19,12 @@
 #include "auth/soup-auth-digest-private.h"
 
 /**
- * SECTION:soup-auth-domain-digest
- * @short_description: Server-side "Digest" authentication
+ * SoupAuthDomainDigest:
+ *
+ * Server-side "Digest" authentication.
  *
  * #SoupAuthDomainDigest handles the server side of HTTP "Digest"
  * authentication.
- **/
-
-/**
- * SoupAuthDomainDigest:
- *
- * Subclass of #SoupAuthDomain for Digest authentication.
  */
 
 enum {
@@ -122,10 +117,11 @@ soup_auth_domain_digest_get_property (GObject *object, guint prop_id,
  * @optname1: name of first option, or %NULL
  * @...: option name/value pairs
  *
- * Creates a #SoupAuthDomainDigest. You must set the
- * SoupAuthDomain:realm property, to indicate the realm name to be
- * returned with the authentication challenge to the client. Other
- * parameters are optional.
+ * Creates a #SoupAuthDomainDigest.
+ *
+ * You must set the [property@AuthDomain:realm] property, to indicate the realm name to
+ * be returned with the authentication challenge to the client. Other parameters
+ * are optional.
  *
  * Returns: the new #SoupAuthDomain
  **/
@@ -150,35 +146,38 @@ soup_auth_domain_digest_new (const char *optname1, ...)
  * @domain: (type SoupAuthDomainDigest): the domain
  * @msg: the message being authenticated
  * @username: the username provided by the client
- * @user_data: the data passed to soup_auth_domain_digest_set_auth_callback()
+ * @user_data: the data passed to [method@AuthDomainDigest.set_auth_callback]
  *
  * Callback used by #SoupAuthDomainDigest for authentication purposes.
+ *
  * The application should look up @username in its password database,
  * and return the corresponding encoded password (see
- * soup_auth_domain_digest_encode_password()).
+ * [func@AuthDomainDigest.encode_password].
  *
  * Returns: (nullable): the encoded password, or %NULL if
- * @username is not a valid user. @domain will free the password when
- * it is done with it.
+ *   @username is not a valid user. @domain will free the password when
+ *   it is done with it.
  **/
 
 /**
- * soup_auth_domain_digest_set_auth_callback:
+ * soup_auth_domain_digest_set_auth_callback: (attributes org.gtk.Method.set_property=auth-callback)
  * @domain: (type SoupAuthDomainDigest): the domain
  * @callback: the callback
  * @user_data: data to pass to @auth_callback
  * @dnotify: destroy notifier to free @user_data when @domain
- * is destroyed
+ *   is destroyed
  *
  * Sets the callback that @domain will use to authenticate incoming
- * requests. For each request containing authorization, @domain will
+ * requests.
+ *
+ * For each request containing authorization, @domain will
  * invoke the callback, and then either accept or reject the request
  * based on @callback's return value.
  *
  * You can also set the auth callback by setting the
- * SoupAuthDomainDigest:auth-callback and
- * SoupAuthDomainDigest:auth-data properties, which can also be
- * used to set the callback at construct time.
+ * [property@AuthDomainDigest:auth-callback] and
+ * [property@AuthDomainDigest:auth-data] properties, which can also be used to
+ * set the callback at construct time.
  **/
 void
 soup_auth_domain_digest_set_auth_callback (SoupAuthDomain *domain,
@@ -354,8 +353,10 @@ soup_auth_domain_digest_challenge (SoupAuthDomain    *domain,
  * @password: the password for @username in @realm
  *
  * Encodes the username/realm/password triplet for Digest
- * authentication. (That is, it returns a stringified MD5 hash of
- * @username, @realm, and @password concatenated together). This is
+ * authentication.
+ *
+ * That is, it returns a stringified MD5 hash of
+ * @username, @realm, and @password concatenated together. This is
  * the form that is needed as the return value of
  * #SoupAuthDomainDigest's auth handler.
  *
@@ -431,9 +432,9 @@ soup_auth_domain_digest_class_init (SoupAuthDomainDigestClass *digest_class)
 	object_class->get_property = soup_auth_domain_digest_get_property;
 
 	/**
-	 * SoupAuthDomainDigest:auth-callback: (type SoupAuthDomainDigestAuthCallback)
+	 * SoupAuthDomainDigest:auth-callback: (type SoupAuthDomainDigestAuthCallback) (attributes org.gtk.Property.set=soup_auth_domain_digest_set_auth_callback)
 	 *
-	 * The #SoupAuthDomainDigestAuthCallback
+	 * The [callback@AuthDomainDigestAuthCallback].
 	 */
         properties[PROP_AUTH_CALLBACK] =
 		g_param_spec_pointer ("auth-callback",
@@ -444,7 +445,7 @@ soup_auth_domain_digest_class_init (SoupAuthDomainDigestClass *digest_class)
 	/**
 	 * SoupAuthDomainDigest:auth-data:
 	 *
-	 * The data to pass to the #SoupAuthDomainDigestAuthCallback
+	 * The data to pass to the [callback@AuthDomainDigestAuthCallback].
 	 */
         properties[PROP_AUTH_DATA] =
 		g_param_spec_pointer ("auth-data",
diff --git a/libsoup/server/soup-auth-domain.c b/libsoup/server/soup-auth-domain.c
index e68884ff..07fe97c2 100644
--- a/libsoup/server/soup-auth-domain.c
+++ b/libsoup/server/soup-auth-domain.c
@@ -17,35 +17,27 @@
 #include "soup-path-map.h"
 
 /**
- * SECTION:soup-auth-domain
- * @short_description: Server-side authentication
- * @see_also: #SoupServer
+ * SoupAuthDomain:
+ *
+ * Server-side authentication.
  *
  * A #SoupAuthDomain manages authentication for all or part of a
- * #SoupServer. To make a server require authentication, first create
+ * [class@Server]. To make a server require authentication, first create
  * an appropriate subclass of #SoupAuthDomain, and then add it to the
- * server with soup_server_add_auth_domain().
- *
- * In order for an auth domain to have any effect, you must add one or
- * more paths to it (via soup_auth_domain_add_path() or the
- * SoupAuthDomain:add-path property). To require authentication for
- * all ordinary requests, add the path "/". (Note that this does not
- * include the special "*" URI (eg, "OPTIONS *"), which must be added
- * as a separate path if you want to cover it.)
- *
- * If you need greater control over which requests should and
- * shouldn't be authenticated, add paths covering everything you
- * <emphasis>might</emphasis> want authenticated, and then use a
- * filter (soup_auth_domain_set_filter()) to bypass authentication for
- * those requests that don't need it.
+ * server with [method@Server.add_auth_domain].
+ *
+ * In order for an auth domain to have any effect, you must add one or more
+ * paths to it (via [method@AuthDomain.add_path]). To require authentication for
+ * all ordinary requests, add the path `"/"`. (Note that this does not include
+ * the special `"*"` URI (eg, "OPTIONS *"), which must be added as a separate
+ * path if you want to cover it.)
+ *
+ * If you need greater control over which requests should and shouldn't be
+ * authenticated, add paths covering everything you *might* want authenticated,
+ * and then use a filter ([method@AuthDomain.set_filter] to bypass
+ * authentication for those requests that don't need it.
  **/
 
-/**
- * SoupAuthDomain:
- *
- * Class managing authentication for #SoupServer.
- */
-
 enum {
 	PROP_0,
 
@@ -183,6 +175,11 @@ soup_auth_domain_class_init (SoupAuthDomainClass *auth_domain_class)
 	object_class->set_property = soup_auth_domain_set_property;
 	object_class->get_property = soup_auth_domain_get_property;
 
+	/**
+	 * SoupAuthDomain:realm: (attributes org.gtk.Property.get=soup_auth_domain_get_realm)
+	 *
+	 * The realm of this auth domain.
+	 */
         properties[PROP_REALM] =
 		g_param_spec_string ("realm",
 				     "Realm",
@@ -191,6 +188,11 @@ soup_auth_domain_class_init (SoupAuthDomainClass *auth_domain_class)
 				     G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY |
 				     G_PARAM_STATIC_STRINGS);
 
+	/**
+	 * SoupAuthDomain:proxy:
+	 *
+	 * Whether or not this is a proxy auth domain.
+	 */
         properties[PROP_PROXY] =
 		g_param_spec_boolean ("proxy",
 				      "Proxy",
@@ -200,9 +202,9 @@ soup_auth_domain_class_init (SoupAuthDomainClass *auth_domain_class)
 				      G_PARAM_STATIC_STRINGS);
 
 	/**
-	 * SoupAuthDomain:filter: (type SoupAuthDomainFilter)
+	 * SoupAuthDomain:filter: (type SoupAuthDomainFilter) (attributes org.gtk.Property.set=soup_auth_domain_set_filter)
 	 *
-	 * The #SoupAuthDomainFilter for the domain.
+	 * The [callback@AuthDomainFilter] for the domain.
 	 */
         properties[PROP_FILTER] =
 		g_param_spec_pointer ("filter",
@@ -213,7 +215,7 @@ soup_auth_domain_class_init (SoupAuthDomainClass *auth_domain_class)
 	/**
 	 * SoupAuthDomain:filter-data:
 	 *
-	 * Data to pass to the #SoupAuthDomainFilter.
+	 * Data to pass to the [callback@AuthDomainFilter].
 	 **/
         properties[PROP_FILTER_DATA] =
 		g_param_spec_pointer ("filter-data",
@@ -222,9 +224,9 @@ soup_auth_domain_class_init (SoupAuthDomainClass *auth_domain_class)
 				      G_PARAM_READWRITE |
 				      G_PARAM_STATIC_STRINGS);
 	/**
-	 * SoupAuthDomain:generic-auth-callback: (type SoupAuthDomainGenericAuthCallback)
+	 * SoupAuthDomain:generic-auth-callback: (type SoupAuthDomainGenericAuthCallback) (attributes org.gtk.Property.set=soup_auth_domain_set_generic_auth_callback)
 	 *
-	 * The #SoupAuthDomainGenericAuthCallback.
+	 * The [callback@AuthDomainGenericAuthCallback].
 	 **/
         properties[PROP_GENERIC_AUTH_CALLBACK] =
 		g_param_spec_pointer ("generic-auth-callback",
@@ -235,7 +237,7 @@ soup_auth_domain_class_init (SoupAuthDomainClass *auth_domain_class)
 	/**
 	 * SoupAuthDomain:generic-auth-data:
 	 *
-         * The data to pass to the #SoupAuthDomainGenericAuthCallback.
+         * The data to pass to the [callback@AuthDomainGenericAuthCallback].
 	 **/
         properties[PROP_GENERIC_AUTH_DATA] =
 		g_param_spec_pointer ("generic-auth-data",
@@ -252,13 +254,11 @@ soup_auth_domain_class_init (SoupAuthDomainClass *auth_domain_class)
  * @domain: a #SoupAuthDomain
  * @path: the path to add to @domain
  *
- * Adds @path to @domain, such that requests under @path on @domain's
- * server will require authentication (unless overridden by
- * soup_auth_domain_remove_path() or soup_auth_domain_set_filter()).
+ * Adds @path to @domain.
  *
- * You can also add paths by setting the SoupAuthDomain:add-path
- * property, which can also be used to add one or more paths at
- * construct time.
+ * Requests under @path on @domain's server will require authentication (unless
+ * overridden by [method@AuthDomain.remove_path] or
+ * [method@AuthDomain.set_filter]).
  **/
 void
 soup_auth_domain_add_path (SoupAuthDomain *domain, const char *path)
@@ -277,20 +277,18 @@ soup_auth_domain_add_path (SoupAuthDomain *domain, const char *path)
  * @domain: a #SoupAuthDomain
  * @path: the path to remove from @domain
  *
- * Removes @path from @domain, such that requests under @path on
- * @domain's server will NOT require authentication.
+ * Removes @path from @domain.
+ *
+ * Requests under @path on @domain's server will NOT require
+ * authentication.
  *
- * This is not simply an undo-er for soup_auth_domain_add_path(); it
+ * This is not simply an undo-er for [method@AuthDomain.add_path]; it
  * can be used to "carve out" a subtree that does not require
  * authentication inside a hierarchy that does. Note also that unlike
- * with soup_auth_domain_add_path(), this cannot be overridden by
+ * with [method@AuthDomain.add_path], this cannot be overridden by
  * adding a filter, as filters can only bypass authentication that
  * would otherwise be required, not require it where it would
  * otherwise be unnecessary.
- *
- * You can also remove paths by setting the
- * SoupAuthDomain:remove-path property, which can also be used to
- * remove one or more paths at construct time.
  **/
 void
 soup_auth_domain_remove_path (SoupAuthDomain *domain, const char *path)
@@ -308,27 +306,29 @@ soup_auth_domain_remove_path (SoupAuthDomain *domain, const char *path)
  * SoupAuthDomainFilter:
  * @domain: a #SoupAuthDomain
  * @msg: a #SoupServerMessage
- * @user_data: the data passed to soup_auth_domain_set_filter()
+ * @user_data: the data passed to [method@AuthDomain.set_filter]
  *
- * The prototype for a #SoupAuthDomain filter; see
- * soup_auth_domain_set_filter() for details.
+ * The prototype for a #SoupAuthDomain filter.
+ *
+ * See [method@AuthDomain.set_filter] for details.
  *
  * Returns: %TRUE if @msg requires authentication, %FALSE if not.
  **/
 
 /**
- * soup_auth_domain_set_filter:
+ * soup_auth_domain_set_filter: (attributes org.gtk.Method.set_property=filter)
  * @domain: a #SoupAuthDomain
  * @filter: the auth filter for @domain
  * @filter_data: data to pass to @filter
  * @dnotify: destroy notifier to free @filter_data when @domain
- * is destroyed
+ *   is destroyed
+ *
+ * Adds @filter as an authentication filter to @domain.
  *
- * Adds @filter as an authentication filter to @domain. The filter
- * gets a chance to bypass authentication for certain requests that
- * would otherwise require it. Eg, it might check the message's path
- * in some way that is too complicated to do via the other methods, or
- * it might check the message's method, and allow GETs but not PUTs.
+ * The filter gets a chance to bypass authentication for certain requests that
+ * would otherwise require it. Eg, it might check the message's path in some way
+ * that is too complicated to do via the other methods, or it might check the
+ * message's method, and allow GETs but not PUTs.
  *
  * The filter function returns %TRUE if the request should still
  * require authentication, or %FALSE if authentication is unnecessary
@@ -346,7 +346,7 @@ soup_auth_domain_remove_path (SoupAuthDomain *domain, const char *path)
  * unauthenticated users.
  *
  * You can also set the filter by setting the SoupAuthDomain:filter
- * and SoupAuthDomain:filter-data properties, which can also be
+ * and [property@AuthDomain:filter-data properties], which can also be
  * used to set the filter at construct time.
  **/
 void
@@ -369,10 +369,10 @@ soup_auth_domain_set_filter (SoupAuthDomain *domain,
 }
 
 /**
- * soup_auth_domain_get_realm:
+ * soup_auth_domain_get_realm: (attributes org.gtk.Method.get_property=realm)
  * @domain: a #SoupAuthDomain
  *
- * Gets the realm name associated with @domain
+ * Gets the realm name associated with @domain.
  *
  * Returns: @domain's realm
  **/
@@ -389,43 +389,43 @@ soup_auth_domain_get_realm (SoupAuthDomain *domain)
  * @domain: a #SoupAuthDomain
  * @msg: the #SoupServerMessage being authenticated
  * @username: the username from @msg
- * @user_data: the data passed to
- * soup_auth_domain_set_generic_auth_callback()
+ * @user_data: the data passed to [method@AuthDomain.set_generic_auth_callback]
  *
  * The prototype for a #SoupAuthDomain generic authentication callback.
  *
  * The callback should look up the user's password, call
- * soup_auth_domain_check_password(), and use the return value from
- * that method as its own return value.
+ * [method@AuthDomain.check_password], and use the return value from that method
+ * as its own return value.
  *
  * In general, for security reasons, it is preferable to use the
  * auth-domain-specific auth callbacks (eg,
- * #SoupAuthDomainBasicAuthCallback and
- * #SoupAuthDomainDigestAuthCallback), because they don't require
+ * [callback@AuthDomainBasicAuthCallback] and
+ * [callback@AuthDomainDigestAuthCallback]), because they don't require
  * keeping a cleartext password database. Most users will use the same
  * password for many different sites, meaning if any site with a
  * cleartext password database is compromised, accounts on other
  * servers might be compromised as well. For many of the cases where
- * #SoupServer is used, this is not really relevant, but it may still
+ * [class@Server] is used, this is not really relevant, but it may still
  * be worth considering.
  *
  * Returns: %TRUE if @msg is authenticated, %FALSE if not.
  **/
 
 /**
- * soup_auth_domain_set_generic_auth_callback:
+ * soup_auth_domain_set_generic_auth_callback: (attributes org.gtk.Method.get_property=generic-auth-callback)
  * @domain: a #SoupAuthDomain
  * @auth_callback: the auth callback
  * @auth_data: data to pass to @auth_callback
  * @dnotify: destroy notifier to free @auth_data when @domain
- * is destroyed
- *
- * Sets @auth_callback as an authentication-handling callback for
- * @domain. Whenever a request comes in to @domain which cannot be
- * authenticated via a domain-specific auth callback (eg,
- * #SoupAuthDomainDigestAuthCallback), the generic auth callback
- * will be invoked. See #SoupAuthDomainGenericAuthCallback for information
- * on what the callback should do.
+ *   is destroyed
+ *
+ * Sets @auth_callback as an authentication-handling callback for @domain.
+ *
+ * Whenever a request comes in to @domain which cannot be authenticated via a
+ * domain-specific auth callback (eg, [callback@AuthDomainDigestAuthCallback]),
+ * the generic auth callback will be invoked. See
+ * [callback@AuthDomainGenericAuthCallback] for information on what the callback
+ * should do.
  **/
 void
 soup_auth_domain_set_generic_auth_callback (SoupAuthDomain *domain,
@@ -467,8 +467,10 @@ soup_auth_domain_try_generic_auth_callback (SoupAuthDomain    *domain,
  * @password: a password
  *
  * Checks if @msg authenticates to @domain via @username and
- * @password. This would normally be called from a
- * #SoupAuthDomainGenericAuthCallback.
+ * @password.
+ *
+ * This would normally be called from a
+ * [callback@AuthDomainGenericAuthCallback].
  *
  * Returns: whether or not the message is authenticated
  **/
@@ -489,11 +491,12 @@ soup_auth_domain_check_password (SoupAuthDomain    *domain,
  * @msg: a #SoupServerMessage
  *
  * Checks if @domain requires @msg to be authenticated (according to
- * its paths and filter function). This does not actually look at
- * whether @msg <emphasis>is</emphasis> authenticated, merely whether
- * or not it needs to be.
+ * its paths and filter function).
+ *
+ * This does not actually look at whether @msg *is* authenticated, merely
+ * whether or not it needs to be.
  *
- * This is used by #SoupServer internally and is probably of no use to
+ * This is used by [class@Server] internally and is probably of no use to
  * anyone else.
  *
  * Returns: %TRUE if @domain requires @msg to be authenticated
@@ -523,15 +526,16 @@ soup_auth_domain_covers (SoupAuthDomain    *domain,
  * @msg: a #SoupServerMessage
  *
  * Checks if @msg contains appropriate authorization for @domain to
- * accept it. Mirroring soup_auth_domain_covers(), this does not check
- * whether or not @domain <emphasis>cares</emphasis> if @msg is
- * authorized.
+ * accept it.
  *
- * This is used by #SoupServer internally and is probably of no use to
+ * Mirroring [method@AuthDomain.covers], this does not check whether or not
+ * @domain *cares* if @msg is authorized.
+ *
+ * This is used by [class@Server] internally and is probably of no use to
  * anyone else.
  *
  * Returns: (nullable): the username that @msg has authenticated
- * as, if in fact it has authenticated. %NULL otherwise.
+ *   as, if in fact it has authenticated. %NULL otherwise.
  **/
 char *
 soup_auth_domain_accepts (SoupAuthDomain    *domain,
@@ -554,11 +558,11 @@ soup_auth_domain_accepts (SoupAuthDomain    *domain,
  * @domain: a #SoupAuthDomain
  * @msg: a #SoupServerMessage
  *
- * Adds a "WWW-Authenticate" or "Proxy-Authenticate" header to @msg,
- * requesting that the client authenticate, and sets @msg's status
- * accordingly.
+ * Adds a "WWW-Authenticate" or "Proxy-Authenticate" header to @msg.
+ *
+ * It requests that the client authenticate, and sets @msg's status accordingly.
  *
- * This is used by #SoupServer internally and is probably of no use to
+ * This is used by [class@Server] internally and is probably of no use to
  * anyone else.
  **/
 void
diff --git a/libsoup/server/soup-message-body.c b/libsoup/server/soup-message-body.c
index 2ab837bc..8c469cbd 100644
--- a/libsoup/server/soup-message-body.c
+++ b/libsoup/server/soup-message-body.c
@@ -15,24 +15,15 @@
 #include "soup.h"
 
 /**
- * SECTION:soup-message-body
- * @short_description: HTTP message body
- * @see_also: #SoupMessage
- *
- * #SoupMessageBody represents the request or response body of a
- * #SoupMessage.
- **/
-
-/**
  * SoupMemoryUse:
  * @SOUP_MEMORY_STATIC: The memory is statically allocated and
- * constant; libsoup can use the passed-in buffer directly and not
- * need to worry about it being modified or freed.
+ *   constant; libsoup can use the passed-in buffer directly and not
+ *   need to worry about it being modified or freed.
  * @SOUP_MEMORY_TAKE: The caller has allocated the memory and libsoup
- * will assume ownership of it and free it with g_free().
+ *   will assume ownership of it and free it with [func@GLib.free].
  * @SOUP_MEMORY_COPY: The passed-in data belongs to the caller and
- * libsoup will copy it into new memory leaving the caller free
- * to reuse the original memory.
+ *   libsoup will copy it into new memory leaving the caller free
+ *   to reuse the original memory.
  *
  * The lifetime of the memory being passed.
  **/
@@ -42,18 +33,19 @@
  * @data: (array length=length) (element-type guint8): the data
  * @length: length of @data
  *
- * A #SoupMessage request or response body.
+ * #SoupMessageBody represents the request or response body of a
+ * [class@Message].
  *
  * Note that while @length always reflects the full length of the
  * message body, @data is normally %NULL, and will only be filled in
- * after soup_message_body_flatten() is called. For client-side
+ * after [method@MessageBody.flatten] is called. For client-side
  * messages, this automatically happens for the response body after it
  * has been fully read. Likewise, for server-side
  * messages, the request body is automatically filled in after being
  * read.
  *
  * As an added bonus, when @data is filled in, it is always terminated
- * with a '\0' byte (which is not reflected in @length).
+ * with a `\0` byte (which is not reflected in @length).
  **/
 
 typedef struct {
@@ -67,7 +59,9 @@ typedef struct {
 /**
  * soup_message_body_new:
  *
- * Creates a new #SoupMessageBody. #SoupMessage uses this internally; you
+ * Creates a new #SoupMessageBody.
+ *
+ * [class@Message] uses this internally; you
  * will not normally need to call it yourself.
  *
  * Returns: a new #SoupMessageBody.
@@ -88,19 +82,19 @@ soup_message_body_new (void)
  * @body: a #SoupMessageBody
  * @accumulate: whether or not to accumulate body chunks in @body
  *
- * Sets or clears the accumulate flag on @body. (The default value is
- * %TRUE.) If set to %FALSE, @body's data field will not be filled in
- * after the body is fully sent/received, and the chunks that make up
- * @body may be discarded when they are no longer needed.
+ * Sets or clears the accumulate flag on @body.
+ *
+ * (The default value is %TRUE.) If set to %FALSE, @body's data field will not
+ * be filled in after the body is fully sent/received, and the chunks that make
+ * up @body may be discarded when they are no longer needed.
  *
- * If you set the flag to %FALSE on the #SoupMessage request_body of a
+ * If you set the flag to %FALSE on the [class@Message] request_body of a
  * client-side message, it will block the accumulation of chunks into
  * @body's data field, but it will not normally cause the chunks to
  * be discarded after being written like in the server-side
- * #SoupMessage response_body case, because the request body needs to
+ * [class@Message] response_body case, because the request body needs to
  * be kept around in case the request needs to be sent a second time
  * due to redirection or authentication.
- *
  **/
 void
 soup_message_body_set_accumulate (SoupMessageBody *body,
@@ -115,11 +109,11 @@ soup_message_body_set_accumulate (SoupMessageBody *body,
  * soup_message_body_get_accumulate:
  * @body: a #SoupMessageBody
  *
- * Gets the accumulate flag on @body; see
- * soup_message_body_set_accumulate() for details.
+ * Gets the accumulate flag on @body.
  *
- * Returns: the accumulate flag for @body.
+ * See [method@MessageBody.set_accumulate. for details.
  *
+ * Returns: the accumulate flag for @body.
  **/
 gboolean
 soup_message_body_get_accumulate (SoupMessageBody *body)
@@ -180,10 +174,9 @@ soup_message_body_append (SoupMessageBody *body, SoupMemoryUse use,
  *
  * Appends @length bytes from @data to @body.
  *
- * This function is exactly equivalent to soup_message_body_append()
+ * This function is exactly equivalent to [method@MessageBody.append]
  * with %SOUP_MEMORY_TAKE as second argument; it exists mainly for
  * convenience and simplifying language bindings.
- *
  **/
 void
 soup_message_body_append_take (SoupMessageBody *body,
@@ -229,8 +222,9 @@ soup_message_body_truncate (SoupMessageBody *body)
  * soup_message_body_complete:
  * @body: a #SoupMessageBody
  *
- * Tags @body as being complete; Call this when using chunked encoding
- * after you have appended the last chunk.
+ * Tags @body as being complete.
+ *
+ * Call this when using chunked encoding after you have appended the last chunk.
  **/
 void
 soup_message_body_complete (SoupMessageBody *body)
@@ -243,11 +237,13 @@ soup_message_body_complete (SoupMessageBody *body)
  * @body: a #SoupMessageBody
  *
  * Fills in @body's data field with a buffer containing all of the
- * data in @body (plus an additional '\0' byte not counted by @body's
- * length field).
+ * data in @body.
  *
- * Return: (transfer full): a #GBytes containing the same data as @body.
- * (You must g_bytes_unref() this if you do not want it.)
+ * Adds an additional `\0` byte not counted by @body's
+ * length field.
+ *
+ * Returns: (transfer full): a #GBytes containing the same data as @body.
+ *   (You must [method@GLib.Bytes.unref] this if you do not want it.)
  **/
 GBytes *
 soup_message_body_flatten (SoupMessageBody *body)
@@ -284,23 +280,24 @@ soup_message_body_flatten (SoupMessageBody *body)
  * @body: a #SoupMessageBody
  * @offset: an offset
  *
- * Gets a #GBytes containing data from @body starting at @offset.
+ * Gets a [struct@GLib.Bytes] containing data from @body starting at @offset.
+ *
  * The size of the returned chunk is unspecified. You can iterate
  * through the entire body by first calling
- * soup_message_body_get_chunk() with an offset of 0, and then on each
+ * [method@MessageBody.get_chunk] with an offset of 0, and then on each
  * successive call, increment the offset by the length of the
  * previously-returned chunk.
  *
  * If @offset is greater than or equal to the total length of @body,
  * then the return value depends on whether or not
- * soup_message_body_complete() has been called or not; if it has,
- * then soup_message_body_get_chunk() will return a 0-length chunk
+ * [method@MessageBody.complete] has been called or not; if it has,
+ * then [method@MessageBody.get_chunk] will return a 0-length chunk
  * (indicating the end of @body). If it has not, then
- * soup_message_body_get_chunk() will return %NULL (indicating that
+ * [method@MessageBody.get_chunk] will return %NULL (indicating that
  * @body may still potentially have more data, but that data is not
  * currently available).
  *
- * Returns: (nullable): a #GBytes, or %NULL.
+ * Returns: (nullable): a #GBytes
  **/
 GBytes *
 soup_message_body_get_chunk (SoupMessageBody *body, goffset offset)
@@ -332,13 +329,14 @@ soup_message_body_get_chunk (SoupMessageBody *body, goffset offset)
  * @chunk: a #GBytes received from the network
  *
  * Handles the #SoupMessageBody part of receiving a chunk of data from
- * the network. Normally this means appending @chunk to @body, exactly
- * as with soup_message_body_append_bytes(), but if you have set
- * @body's accumulate flag to %FALSE, then that will not happen.
+ * the network.
+ *
+ * Normally this means appending @chunk to @body, exactly as with
+ * [method@MessageBody.append_bytes], but if you have set @body's accumulate
+ * flag to %FALSE, then that will not happen.
  *
  * This is a low-level method which you should not normally need to
  * use.
- *
  **/
 void
 soup_message_body_got_chunk (SoupMessageBody *body, GBytes *chunk)
@@ -354,17 +352,17 @@ soup_message_body_got_chunk (SoupMessageBody *body, GBytes *chunk)
 /**
  * soup_message_body_wrote_chunk:
  * @body: a #SoupMessageBody
- * @chunk: a #GBytes returned from soup_message_body_get_chunk()
+ * @chunk: a #GBytes returned from [method@MessageBody.get_chunk]
  *
  * Handles the #SoupMessageBody part of writing a chunk of data to the
- * network. Normally this is a no-op, but if you have set @body's
- * accumulate flag to %FALSE, then this will cause @chunk to be
- * discarded to free up memory.
+ * network.
+ *
+ * Normally this is a no-op, but if you have set @body's accumulate flag to
+ * %FALSE, then this will cause @chunk to be discarded to free up memory.
  *
  * This is a low-level method which you should not need to use, and
  * there are further restrictions on its proper use which are not
  * documented here.
- *
  **/
 void
 soup_message_body_wrote_chunk (SoupMessageBody *body, GBytes *chunk)
@@ -408,6 +406,7 @@ soup_message_body_ref (SoupMessageBody *body)
  * @body: a #SoupMessageBody
  *
  * Atomically decrements the reference count of @body by one.
+ *
  * When the reference count reaches zero, the resources allocated by
  * @body are freed
  */
diff --git a/libsoup/server/soup-path-map.c b/libsoup/server/soup-path-map.c
index aeaf8e46..25b67b72 100644
--- a/libsoup/server/soup-path-map.c
+++ b/libsoup/server/soup-path-map.c
@@ -34,7 +34,7 @@ struct SoupPathMap {
 /**
  * soup_path_map_new:
  * @data_free_func: function to use to free data added with
- * soup_path_map_add().
+ *   soup_path_map_add().
  *
  * Creates a new %SoupPathMap.
  *
@@ -176,7 +176,7 @@ soup_path_map_remove (SoupPathMap *map, const char *path)
  * closest parent directory of @path that has data associated with it.
  *
  * Returns: (nullable): the data set with soup_path_map_add(), or
- * %NULL if no data could be found for @path or any of its ancestors.
+ *   %NULL if no data could be found for @path or any of its ancestors.
  **/
 gpointer
 soup_path_map_lookup (SoupPathMap *map, const char *path)
diff --git a/libsoup/server/soup-server-message.c b/libsoup/server/soup-server-message.c
index 8250fd26..fdf7d5b9 100644
--- a/libsoup/server/soup-server-message.c
+++ b/libsoup/server/soup-server-message.c
@@ -19,29 +19,22 @@
 #include "soup-uri-utils-private.h"
 
 /**
- * SECTION:soup-server-message
- * @short_description: An HTTP server request and response.
- * @see_also: #SoupMessageHeaders, #SoupMessageBody
+ * SoupServerMessage:
+ *
+ * An HTTP server request and response pair.
  *
  * A SoupServerMessage represents an HTTP message that is being sent or
- * received on a #SoupServer
+ * received on a [class@Server].
  *
- * #SoupServer will create #SoupServerMessage<!-- -->s automatically for
+ * [class@Server] will create `SoupServerMessage`s automatically for
  * incoming requests, which your application will receive via handlers.
  *
  * Note that libsoup's terminology here does not quite match the HTTP
- * specification: in RFC 2616, an "HTTP-message" is
- * <emphasis>either</emphasis> a Request, <emphasis>or</emphasis> a
- * Response. In libsoup, a #SoupServerMessage combines both the request and
- * the response.
+ * specification: in RFC 2616, an "HTTP-message" is *either* a Request, *or* a
+ * Response. In libsoup, a #SoupServerMessage combines both the request and the
+ * response.
  **/
 
-/**
- * SoupServerMessage:
- *
- * Class represnting an HTTP request and response pair for a server.
- */
-
 struct _SoupServerMessage {
         GObject             parent;
 
@@ -186,11 +179,11 @@ soup_server_message_class_init (SoupServerMessageClass *klass)
          * Emitted immediately after writing a body chunk for a message.
          *
          * Note that this signal is not parallel to
-         * #SoupServerMessage::got-chunk; it is emitted only when a complete
-         * chunk (added with soup_message_body_append() or
-         * soup_message_body_append_bytes()) has been written. To get
+         * [signal@ServerMessage::got-chunk]; it is emitted only when a complete
+         * chunk (added with [method@MessageBody.append] or
+         * [method@MessageBody.append_bytes] has been written. To get
          * more useful continuous progress information, use
-         * #SoupServerMessage::wrote-body-data.
+         * [signal@ServerMessage::wrote-body-data].
          */
         signals[WROTE_CHUNK] =
                 g_signal_new ("wrote-chunk",
@@ -255,10 +248,10 @@ soup_server_message_class_init (SoupServerMessageClass *klass)
          * @msg: the message
          * @chunk: the just-read chunk
          *
-         * Emitted after receiving a chunk of a message body. Note
-         * that "chunk" in this context means any subpiece of the
-         * body, not necessarily the specific HTTP 1.1 chunks sent by
-         * the other side.
+         * Emitted after receiving a chunk of a message body.
+         *
+         * Note that "chunk" in this context means any subpiece of the body, not
+         * necessarily the specific HTTP 1.1 chunks sent by the other side.
          */
         signals[GOT_CHUNK] =
                 g_signal_new ("got-chunk",
@@ -290,7 +283,7 @@ soup_server_message_class_init (SoupServerMessageClass *klass)
          * @msg: the message
          *
          * Emitted when all HTTP processing is finished for a message.
-         * (After #SoupServerMessage::wrote-body).
+         * (After [signal@ServerMessage::wrote-body]).
          */
         signals[FINISHED] =
                 g_signal_new ("finished",
@@ -328,8 +321,8 @@ soup_server_message_class_init (SoupServerMessageClass *klass)
 	 * @tls_errors.
 	 *
 	 * Returns: %TRUE to accept the TLS certificate and stop other
-	 *     handlers from being invoked, or %FALSE to propagate the
-	 *     event further.
+	 *   handlers from being invoked, or %FALSE to propagate the
+	 *   event further.
 	 */
 	signals[ACCEPT_CERTIFICATE] =
 		g_signal_new ("accept-certificate",
@@ -680,7 +673,7 @@ soup_server_message_set_http_version (SoupServerMessage *msg,
  * soup_server_message_get_reason_phrase:
  * @msg: a #SoupServerMessage:
  *
- * Get the HTTP reason phrase of @msg or %NULL.
+ * Get the HTTP reason phrase of @msg.
  *
  * Returns: (nullable): the reason phrase.
  */
@@ -714,9 +707,10 @@ soup_server_message_get_status (SoupServerMessage *msg)
  * @status_code: an HTTP status code
  * @reason_phrase: (nullable): a reason phrase
  *
- * Sets @msg's status code to @status_code. If @status_code is a
- * known value and @reason_phrase is %NULL, the reason_phrase will
- * be set automatically.
+ * Sets @msg's status code to @status_code.
+ *
+ * If @status_code is a known value and @reason_phrase is %NULL, the
+ * reason_phrase will be set automatically.
  **/
 void
 soup_server_message_set_status (SoupServerMessage *msg,
@@ -792,13 +786,13 @@ soup_server_message_set_response (SoupServerMessage *msg,
  * @redirect_uri: the URI to redirect @msg to
  *
  * Sets @msg's status_code to @status_code and adds a Location header
- * pointing to @redirect_uri. Use this from a #SoupServer when you
+ * pointing to @redirect_uri. Use this from a [class@Server] when you
  * want to redirect the client to another URI.
  *
  * @redirect_uri can be a relative URI, in which case it is
  * interpreted relative to @msg's current URI. In particular, if
  * @redirect_uri is just a path, it will replace the path
- * <emphasis>and query</emphasis> of @msg's URI.
+ * *and query* of @msg's URI.
  */
 void
 soup_server_message_set_redirect (SoupServerMessage *msg,
@@ -825,7 +819,7 @@ soup_server_message_set_redirect (SoupServerMessage *msg,
  * soup_server_message_get_socket:
  * @msg: a #SoupServerMessage
  *
- * Retrieves the #GSocket that @msg is associated with.
+ * Retrieves the [class@Gio.Socket] that @msg is associated with.
  *
  * If you are using this method to observe when multiple requests are
  * made on the same persistent HTTP connection (eg, as the ntlm-test
@@ -835,7 +829,7 @@ soup_server_message_set_redirect (SoupServerMessage *msg,
  * previously-destroyed socket to represent a new socket.
  *
  * Returns: (nullable) (transfer none): the #GSocket that @msg is
- * associated with, %NULL if you used soup_server_accept_iostream().
+ *   associated with, %NULL if you used [method@Server.accept_iostream].
  */
 GSocket *
 soup_server_message_get_socket (SoupServerMessage *msg)
@@ -849,12 +843,12 @@ soup_server_message_get_socket (SoupServerMessage *msg)
  * soup_server_message_get_remote_address:
  * @msg: a #SoupServerMessage
  *
- * Retrieves the #GSocketAddress associated with the remote end
+ * Retrieves the [class@Gio.SocketAddress] associated with the remote end
  * of a connection.
  *
  * Returns: (nullable) (transfer none): the #GSocketAddress
- *     associated with the remote end of a connection, it may be
- *     %NULL if you used soup_server_accept_iostream().
+ *   associated with the remote end of a connection, it may be
+ *   %NULL if you used [class@Server.accept_iostream].
  */
 GSocketAddress *
 soup_server_message_get_remote_address (SoupServerMessage *msg)
@@ -875,12 +869,12 @@ soup_server_message_get_remote_address (SoupServerMessage *msg)
  * soup_server_message_get_local_address:
  * @msg: a #SoupServerMessage
  *
- * Retrieves the #GSocketAddress associated with the local end
+ * Retrieves the [class@Gio.SocketAddress] associated with the local end
  * of a connection.
  *
  * Returns: (nullable) (transfer none): the #GSocketAddress
- *     associated with the local end of a connection, it may be
- *     %NULL if you used soup_server_accept_iostream().
+ *   associated with the local end of a connection, it may be
+ *   %NULL if you used [method@Server.accept_iostream].
  */
 GSocketAddress *
 soup_server_message_get_local_address (SoupServerMessage *msg)
@@ -905,8 +899,8 @@ soup_server_message_get_local_address (SoupServerMessage *msg)
  * connection.
  *
  * Returns: (nullable): the IP address associated with the remote
- *     end of a connection, it may be %NULL if you used
- *     soup_server_accept_iostream().
+ *   end of a connection, it may be %NULL if you used
+ *   [method@Server.accept_iostream].
  */
 const char *
 soup_server_message_get_remote_host (SoupServerMessage *msg)
@@ -937,12 +931,13 @@ soup_server_message_get_remote_host (SoupServerMessage *msg)
  * soup_server_message_steal_connection:
  * @msg: a #SoupServerMessage
  *
- * "Steals" the HTTP connection associated with @msg from its
- * #SoupServer. This happens immediately, regardless of the current
- * state of the connection; if the response to @msg has not yet finished
- * being sent, then it will be discarded; you can steal the connection from a
- * #SoupServerMessage::wrote-informational or #SoupServerMessage::wrote-body signal
- * handler if you need to wait for part or all of the response to be sent.
+ * "Steals" the HTTP connection associated with @msg from its #SoupServer. This
+ * happens immediately, regardless of the current state of the connection; if
+ * the response to @msg has not yet finished being sent, then it will be
+ * discarded; you can steal the connection from a
+ * [signal@ServerMessage::wrote-informational] or
+ * [signal@ServerMessage::wrote-body] signal handler if you need to wait for
+ * part or all of the response to be sent.
  *
  * Note that when calling this function from C, @msg will most
  * likely be freed as a side effect.
diff --git a/libsoup/server/soup-server.c b/libsoup/server/soup-server.c
index 14b2f2f7..63e39a95 100644
--- a/libsoup/server/soup-server.c
+++ b/libsoup/server/soup-server.c
@@ -26,50 +26,44 @@
 #include "websocket/soup-websocket-extension-deflate.h"
 
 /**
- * SECTION:soup-server
- * @short_description: HTTP server
- * @see_also: #SoupAuthDomain
+ * SoupServer:
+ *
+ * A HTTP server.
  *
  * #SoupServer implements a simple HTTP server.
  *
- * (The following documentation describes the current #SoupServer API,
- * available in <application>libsoup</application> 2.48 and later. See
- * the section "<link linkend="soup-server-old-api">The Old SoupServer
- * Listening API</link>" in the server how-to documentation for
- * details on the older #SoupServer API.)
- * 
- * To begin, create a server using soup_server_new(). Add at least one
- * handler by calling soup_server_add_handler() or
- * soup_server_add_early_handler(); the handler will be called to
+ * To begin, create a server using [ctor@Server.new]. Add at least one
+ * handler by calling [method@Server.add_handler] or
+ * [method@Server.add_early_handler]; the handler will be called to
  * process any requests underneath the path you pass. (If you want all
  * requests to go to the same handler, just pass "/" (or %NULL) for
  * the path.)
  *
  * When a new connection is accepted (or a new request is started on
  * an existing persistent connection), the #SoupServer will emit
- * #SoupServer::request-started and then begin processing the request
+ * [signal@Server::request-started] and then begin processing the request
  * as described below, but note that once the message is assigned a
  * status-code, then callbacks after that point will be
  * skipped. Note also that it is not defined when the callbacks happen
- * relative to various #SoupServerMessage signals.
+ * relative to various [class@ServerMessage] signals.
  *
  * Once the headers have been read, #SoupServer will check if there is
- * a #SoupAuthDomain (qv) covering the Request-URI; if so, and if the
+ * a [class@AuthDomain] `(qv)` covering the Request-URI; if so, and if the
  * message does not contain suitable authorization, then the
- * #SoupAuthDomain will set a status of %SOUP_STATUS_UNAUTHORIZED on
+ * [class@AuthDomain] will set a status of %SOUP_STATUS_UNAUTHORIZED on
  * the message.
  *
  * After checking for authorization, #SoupServer will look for "early"
- * handlers (added with soup_server_add_early_handler()) matching the
+ * handlers (added with [method@Server.add_early_handler]) matching the
  * Request-URI. If one is found, it will be run; in particular, this
  * can be used to connect to signals to do a streaming read of the
  * request body.
  *
- * (At this point, if the request headers contain "<literal>Expect:
- * 100-continue</literal>", and a status code has been set, then
+ * (At this point, if the request headers contain `Expect:
+ * 100-continue`, and a status code has been set, then
  * #SoupServer will skip the remaining steps and return the response.
- * If the request headers contain "<literal>Expect:
- * 100-continue</literal>" and no status code has been set,
+ * If the request headers contain `Expect:
+ * 100-continue` and no status code has been set,
  * #SoupServer will return a %SOUP_STATUS_CONTINUE status before
  * continuing.)
  *
@@ -80,7 +74,7 @@
  *
  * Otherwise (assuming no previous step assigned a status to the
  * message) any "normal" handlers (added with
- * soup_server_add_handler()) for the message's Request-URI will be
+ * [method@Server.add_handler]) for the message's Request-URI will be
  * run.
  *
  * Then, if the path has a WebSocket handler registered (and has
@@ -90,12 +84,12 @@
  * %SOUP_STATUS_BAD_REQUEST accordingly.
  *
  * If the message still has no status code at this point (and has not
- * been paused with soup_server_pause_message()), then it will be
+ * been paused with [method@Server.pause_message]), then it will be
  * given a status of %SOUP_STATUS_INTERNAL_SERVER_ERROR (because at
  * least one handler ran, but returned without assigning a status).
  *
- * Finally, the server will emit #SoupServer::request-finished (or
- * #SoupServer::request-aborted if an I/O error occurred before
+ * Finally, the server will emit [signal@Server::request-finished] (or
+ * [signal@Server::request-aborted] if an I/O error occurred before
  * handling was completed).
  *
  * If you want to handle the special "*" URI (eg, "OPTIONS *"), you
@@ -103,27 +97,21 @@
  * will not be used for that case.
  *
  * If you want to process https connections in addition to (or instead
- * of) http connections, you can set the #SoupServer:tls-certificate
+ * of) http connections, you can set the [property@Server:tls-certificate]
  * property.
  *
  * Once the server is set up, make one or more calls to
- * soup_server_listen(), soup_server_listen_local(), or
- * soup_server_listen_all() to tell it where to listen for
+ * [method@Server.listen], [method@Server.listen_local], or
+ * [method@Server.listen_all] to tell it where to listen for
  * connections. (All ports on a #SoupServer use the same handlers; if
  * you need to handle some ports differently, such as returning
  * different data for http and https, you'll need to create multiple
- * #SoupServers, or else check the passed-in URI in the handler
+ * `SoupServer`s, or else check the passed-in URI in the handler
  * function.).
  *
  * #SoupServer will begin processing connections as soon as you return
  * to (or start) the main loop for the current thread-default
- * #GMainContext.
- */
-
-/**
- * SoupServer:
- *
- * Class implementing an HTTP server.
+ * [struct@GLib.MainContext].
  */
 
 enum {
@@ -352,16 +340,17 @@ soup_server_class_init (SoupServerClass *server_class)
 	 * @message: the new message
 	 *
 	 * Emitted when the server has started reading a new request.
+	 *
 	 * @message will be completely blank; not even the
 	 * Request-Line will have been read yet. About the only thing
 	 * you can usefully do with it is connect to its signals.
 	 *
 	 * If the request is read successfully, this will eventually
-	 * be followed by a #SoupServer::request_read signal. If a
+	 * be followed by a [signal@Server::request_read signal]. If a
 	 * response is then sent, the request processing will end with
-	 * a #SoupServer::request_finished signal. If a network error
+	 * a [signal@Server::request-finished] signal. If a network error
 	 * occurs, the processing will instead end with
-	 * #SoupServer::request_aborted.
+	 * [signal@Server::request-aborted].
 	 **/
 	signals[REQUEST_STARTED] =
 		g_signal_new ("request-started",
@@ -379,6 +368,7 @@ soup_server_class_init (SoupServerClass *server_class)
 	 * @message: the message
 	 *
 	 * Emitted when the server has successfully read a request.
+	 *
 	 * @message will have all of its request-side information
 	 * filled in, and if the message was authenticated, @client
 	 * will have information about that. This signal is emitted
@@ -419,17 +409,17 @@ soup_server_class_init (SoupServerClass *server_class)
 	 * @server: the server
 	 * @message: the message
 	 *
-	 * Emitted when processing has failed for a message; this
-	 * could mean either that it could not be read (if
-	 * #SoupServer::request_read has not been emitted for it yet),
-	 * or that the response could not be written back (if
-	 * #SoupServer::request_read has been emitted but
-	 * #SoupServer::request_finished has not been).
+	 * Emitted when processing has failed for a message.
+	 *
+	 * This could mean either that it could not be read (if
+	 * [signal@Server::request-read] has not been emitted for it yet), or that
+	 * the response could not be written back (if [signal@Server::request-read]
+	 * has been emitted but [signal@Server::request-finished] has not been).
 	 *
 	 * @message is in an undefined state when this signal is
 	 * emitted; the signal exists primarily to allow the server to
 	 * free any state that it may have allocated in
-	 * #SoupServer::request_started.
+	 * [signal@Server::request-started].
 	 **/
 	signals[REQUEST_ABORTED] =
 		g_signal_new ("request-aborted",
@@ -443,10 +433,12 @@ soup_server_class_init (SoupServerClass *server_class)
 
 	/* properties */
 	/**
-	 * SoupServer:tls-certificate:
+	 * SoupServer:tls-certificate: (attributes org.gtk.Property.get=soup_server_get_tls_certificate org.gtk.Property.set=soup_server_set_tls_certificate)
 	 *
-	 * A #GTlsCertificate that has a #GTlsCertificate:private-key
-	 * set. If this is set, then the server will be able to speak
+	 * A [class@Gio.TlsCertificate[] that has a
+	 * [property@Gio.TlsCertificate:private-key] set.
+	 *
+	 * If this is set, then the server will be able to speak
 	 * https in addition to (or instead of) plain http.
 	 */
         properties[PROP_TLS_CERTIFICATE] =
@@ -459,9 +451,10 @@ soup_server_class_init (SoupServerClass *server_class)
                                      G_PARAM_STATIC_STRINGS);
 
         /**
-         * SoupServer:tls-database:
+         * SoupServer:tls-database: (attributes org.gtk.Property.get=soup_server_get_tls_database org.gtk.Property.set=soup_server_set_tls_database)
          *
-         * A #GTlsDatabase to use for validating SSL/TLS client certificates.
+         * A [class@Gio.TlsDatabase] to use for validating SSL/TLS client
+         * certificates.
          */
         properties[PROP_TLS_DATABASE] =
                 g_param_spec_object ("tls-database",
@@ -473,9 +466,9 @@ soup_server_class_init (SoupServerClass *server_class)
                                      G_PARAM_STATIC_STRINGS);
 
         /**
-         * SoupServer:tls-auth-mode:
+         * SoupServer:tls-auth-mode: (attributes org.gtk.Property.get=soup_server_get_tls_auth_mode org.gtk.Property.set=soup_server_set_tls_auth_mode)
          *
-         * A #GTlsAuthenticationMode for SSL/TLS client authentication
+         * A [enum@Gio.TlsAuthenticationMode] for SSL/TLS client authentication.
          */
         properties[PROP_TLS_AUTH_MODE] =
                 g_param_spec_enum ("tls-auth-mode",
@@ -487,6 +480,12 @@ soup_server_class_init (SoupServerClass *server_class)
                                    G_PARAM_CONSTRUCT |
                                    G_PARAM_STATIC_STRINGS);
 
+        /**
+         * SoupServer:raw-paths:
+         *
+         * If %TRUE, percent-encoding in the Request-URI path will not be
+         * automatically decoded.
+         */
         properties[PROP_RAW_PATHS] =
 		g_param_spec_boolean ("raw-paths",
 				      "Raw paths",
@@ -499,8 +498,10 @@ soup_server_class_init (SoupServerClass *server_class)
 	/**
 	 * SoupServer:server-header:
 	 *
+	 * Server header.
+	 *
 	 * If non-%NULL, the value to use for the "Server" header on
-	 * #SoupServerMessage<!-- -->s processed by this server.
+	 * [class@ServerMessage]s processed by this server.
 	 *
 	 * The Server header is the server equivalent of the
 	 * User-Agent header, and provides information about the
@@ -518,11 +519,10 @@ soup_server_class_init (SoupServerClass *server_class)
 	 * end up advertising their vulnerability to specific security
 	 * holes.
 	 *
-	 * As with #SoupSession:user_agent, if you set a
-	 * #SoupServer:server_header property that has trailing whitespace,
-	 * #SoupServer will append its own product token (eg,
-	 * "<literal>libsoup/2.3.2</literal>") to the end of the
-	 * header for you.
+	 * As with [property@Session:user_agent], if you set a
+	 * [property@Server:server-header] property that has trailing
+	 * whitespace, #SoupServer will append its own product token (eg,
+	 * `libsoup/2.3.2`) to the end of the header for you.
 	 **/
         properties[PROP_SERVER_HEADER] =
 		g_param_spec_string ("server-header",
@@ -541,12 +541,14 @@ soup_server_class_init (SoupServerClass *server_class)
  * @optname1: name of first property to set
  * @...: value of @optname1, followed by additional property/value pairs
  *
- * Creates a new #SoupServer. This is exactly equivalent to calling
- * g_object_new() and specifying %SOUP_TYPE_SERVER as the type.
+ * Creates a new #SoupServer.
+ *
+ * This is exactly equivalent to calling [ctor@GObject.Object.new] and
+ * specifying %SOUP_TYPE_SERVER as the type.
  *
  * Returns: (nullable): a new #SoupServer. If you are using
- * certain legacy properties, this may also return %NULL if an error
- * occurs.
+ *   certain legacy properties, this may also return %NULL if an error
+ *   occurs.
  **/
 SoupServer *
 soup_server_new (const char *optname1, ...)
@@ -563,7 +565,7 @@ soup_server_new (const char *optname1, ...)
 }
 
 /**
- * soup_server_set_tls_certificate:
+ * soup_server_set_tls_certificate: (attributes org.gtk.Method.set_property=tls-certificate)
  * @server: a #SoupServer
  * @certificate: a #GTlsCertificate
  *
@@ -587,10 +589,10 @@ soup_server_set_tls_certificate (SoupServer      *server,
 }
 
 /**
- * soup_server_get_tls_certificate:
+ * soup_server_get_tls_certificate: (attributes org.gtk.Method.get_property=tls-certificate)
  * @server: a #SoupServer
  *
- * Gets the @server SSL/TLS certificate
+ * Gets the @server SSL/TLS certificate.
  *
  * Returns: (transfer none) (nullable): a #GTlsCertificate or %NULL
  */
@@ -606,11 +608,11 @@ soup_server_get_tls_certificate (SoupServer *server)
 }
 
 /**
- * soup_server_set_tls_database:
+ * soup_server_set_tls_database: (attributes org.gtk.Method.set_property=tls-database)
  * @server: a #SoupServer
  * @tls_database: a #GTlsDatabase
  *
- * Sets @server's #GTlsDatabase to use for validating SSL/TLS client certificates
+ * Sets @server's #GTlsDatabase to use for validating SSL/TLS client certificates.
  */
 void
 soup_server_set_tls_database (SoupServer   *server,
@@ -630,12 +632,12 @@ soup_server_set_tls_database (SoupServer   *server,
 }
 
 /**
- * soup_server_get_tls_database:
+ * soup_server_get_tls_database: (attributes org.gtk.Method.get_property=tls-database)
  * @server: a #SoupServer
  *
- * Gets the @server SSL/TLS database
+ * Gets the @server SSL/TLS database.
  *
- * Returns: (transfer none) (nullable): a #GTlsDatabase or %NULL
+ * Returns: (transfer none) (nullable): a #GTlsDatabase
  */
 GTlsDatabase *
 soup_server_get_tls_database (SoupServer *server)
@@ -649,11 +651,11 @@ soup_server_get_tls_database (SoupServer *server)
 }
 
 /**
- * soup_server_set_tls_auth_mode:
+ * soup_server_set_tls_auth_mode: (attributes org.gtk.Method.set_property=tls-auth-mode)
  * @server: a #SoupServer
  * @mode: a #GTlsAuthenticationMode
  *
- * Sets @server's #GTlsAuthenticationMode to use for SSL/TLS client authentication
+ * Sets @server's #GTlsAuthenticationMode to use for SSL/TLS client authentication.
  */
 void
 soup_server_set_tls_auth_mode (SoupServer             *server,
@@ -672,10 +674,10 @@ soup_server_set_tls_auth_mode (SoupServer             *server,
 }
 
 /**
- * soup_server_get_tls_auth_mode:
+ * soup_server_get_tls_auth_mode: (attributes org.gtk.Method.get_property=tls-auth-mode)
  * @server: a #SoupServer
  *
- * Gets the @server SSL/TLS client authentication mode
+ * Gets the @server SSL/TLS client authentication mode.
  *
  * Returns: a #GTlsAuthenticationMode
  */
@@ -697,17 +699,16 @@ soup_server_get_tls_auth_mode (SoupServer *server)
  * Checks whether @server is capable of https.
  *
  * In order for a server to run https, you must call
- * soup_server_set_ssl_cert_file(), or set the
- * #SoupServer:tls-certificate property, to provide it with a
+ * [method@Server.set_tls_certificate], or set the
+ * [property@Server:tls-certificate] property, to provide it with a
  * certificate to use.
  *
- * If you are using the deprecated single-listener APIs, then a return
- * value of %TRUE indicates that the #SoupServer serves https
- * exclusively. If you are using soup_server_listen(), etc, then a
- * %TRUE return value merely indicates that the server is
- * <emphasis>able</emphasis> to do https, regardless of whether it
- * actually currently is or not. Use soup_server_get_uris() to see if
- * it currently has any https listeners.
+ * If you are using the deprecated single-listener APIs, then a return value of
+ * %TRUE indicates that the #SoupServer serves https exclusively. If you are
+ * using [method@Server.listen], etc, then a %TRUE return value merely indicates
+ * that the server is *able* to do https, regardless of whether it actually
+ * currently is or not. Use [method@Server.get_uris] to see if it currently has
+ * any https listeners.
  *
  * Returns: %TRUE if @server is configured to serve https.
  **/
@@ -732,7 +733,7 @@ soup_server_is_https (SoupServer *server)
  * modifiying any of these sockets may cause @server to malfunction.
  *
  * Returns: (transfer container) (element-type Gio.Socket): a
- * list of listening sockets.
+ *   list of listening sockets.
  **/
 GSList *
 soup_server_get_listeners (SoupServer *server)
@@ -1084,16 +1085,17 @@ start_request (SoupServer        *server,
  * soup_server_accept_iostream:
  * @server: a #SoupServer
  * @stream: a #GIOStream
- * @local_addr: (nullable): the local #GSocketAddress associated with the @stream
- * @remote_addr: (nullable): the remote #GSocketAddress associated with the @stream
+ * @local_addr: (nullable): the local #GSocketAddress associated with the
+ *   @stream
+ * @remote_addr: (nullable): the remote #GSocketAddress associated with the
+ *   @stream
  * @error: return location for a #GError
  *
- * Add a new client stream to the @server.
+ * Adds a new client stream to the @server.
  *
  * Returns: %TRUE on success, %FALSE if the stream could not be
- * accepted or any other error occurred (in which case @error will be
- * set).
- *
+ *   accepted or any other error occurred (in which case @error will be
+ *   set).
  **/
 gboolean
 soup_server_accept_iostream (SoupServer     *server,
@@ -1133,11 +1135,11 @@ new_connection (SoupSocket *listener, SoupSocket *sock, gpointer user_data)
  *
  * 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
- * is still running.
+ * Note that if there are currently requests in progress on @server, that they
+ * will continue to be processed if @server's [struct@GLib.MainContext] is still
+ * running.
  *
- * You can call soup_server_listen(), etc, after calling this function
+ * You can call [method@Server.listen], etc, after calling this function
  * if you want to start listening again.
  **/
 void
@@ -1177,14 +1179,13 @@ soup_server_disconnect (SoupServer *server)
  * @SOUP_SERVER_LISTEN_IPV4_ONLY: Only listen on IPv4 interfaces.
  * @SOUP_SERVER_LISTEN_IPV6_ONLY: Only listen on IPv6 interfaces.
  *
- * Options to pass to soup_server_listen(), etc.
+ * Options to pass to [method@Server.listen], etc.
  *
  * %SOUP_SERVER_LISTEN_IPV4_ONLY and %SOUP_SERVER_LISTEN_IPV6_ONLY
- * only make sense with soup_server_listen_all() and
- * soup_server_listen_local(), not plain soup_server_listen() (which
+ * only make sense with [method@Server.listen_all] and
+ * [method@Server.listen_local], not plain [method@Server.listen] (which
  * simply listens on whatever kind of socket you give it). And you
  * cannot specify both of them in a single call.
- *
  */
 
 static gboolean
@@ -1246,8 +1247,7 @@ soup_server_listen_internal (SoupServer *server, SoupSocket *listener,
  * @options: listening options for this server
  * @error: return location for a #GError
  *
- * This attempts to set up @server to listen for connections on
- * @address.
+ * Attempts to set up @server to listen for connections on @address.
  *
  * If @options includes %SOUP_SERVER_LISTEN_HTTPS, and @server has
  * been configured for TLS, then @server will listen for https
@@ -1257,18 +1257,16 @@ soup_server_listen_internal (SoupServer *server, SoupSocket *listener,
  * any number of times on a server, if you want to listen on multiple
  * ports, or set up both http and https service.
  *
- * After calling this method, @server will begin accepting and
- * processing connections as soon as the appropriate #GMainContext is
- * run.
+ * After calling this method, @server will begin accepting and processing
+ * connections as soon as the appropriate [struct@GLib.MainContext] is run.
  *
  * Note that #SoupServer never makes use of dual IPv4/IPv6 sockets; if
  * @address is an IPv6 address, it will only accept IPv6 connections.
  * You must configure IPv4 listening separately.
  *
  * Returns: %TRUE on success, %FALSE if @address could not be
- * bound or any other error occurred (in which case @error will be
- * set).
- *
+ *   bound or any other error occurred (in which case @error will be
+ *   set).
  **/
 gboolean
 soup_server_listen (SoupServer *server, GSocketAddress *address,
@@ -1378,20 +1376,20 @@ soup_server_listen_ipv4_ipv6 (SoupServer *server,
  * @options: listening options for this server
  * @error: return location for a #GError
  *
- * This attempts to set up @server to listen for connections on all
- * interfaces on the system. (That is, it listens on the addresses
- * <literal>0.0.0.0</literal> and/or <literal>::</literal>, depending
- * on whether @options includes %SOUP_SERVER_LISTEN_IPV4_ONLY,
- * %SOUP_SERVER_LISTEN_IPV6_ONLY, or neither.) If @port is specified,
- * @server will listen on that port. If it is 0, @server will find an
- * unused port to listen on. (In that case, you can use
- * soup_server_get_uris() to find out what port it ended up choosing.)
+ * Attempts to set up @server to listen for connections on all interfaces
+ * on the system.
  *
- * See soup_server_listen() for more details.
+ * That is, it listens on the addresses `0.0.0.0` and/or `::`, depending on
+ * whether @options includes %SOUP_SERVER_LISTEN_IPV4_ONLY,
+ * %SOUP_SERVER_LISTEN_IPV6_ONLY, or neither.) If @port is specified, @server
+ * will listen on that port. If it is 0, @server will find an unused port to
+ * listen on. (In that case, you can use [method@Server.get_uris] to find out
+ * what port it ended up choosing.
  *
- * Returns: %TRUE on success, %FALSE if @port could not be bound
- * or any other error occurred (in which case @error will be set).
+ * See [method@Server.listen] for more details.
  *
+ * Returns: %TRUE on success, %FALSE if @port could not be bound
+ *   or any other error occurred (in which case @error will be set).
  **/
 gboolean 
 soup_server_listen_all (SoupServer *server, guint port,
@@ -1431,20 +1429,18 @@ soup_server_listen_all (SoupServer *server, guint port,
  * @options: listening options for this server
  * @error: return location for a #GError
  *
- * This attempts to set up @server to listen for connections on
- * "localhost" (that is, <literal>127.0.0.1</literal> and/or
- * <literal>::1</literal>, depending on whether @options includes
- * %SOUP_SERVER_LISTEN_IPV4_ONLY, %SOUP_SERVER_LISTEN_IPV6_ONLY, or
- * neither). If @port is specified, @server will listen on that port.
- * If it is 0, @server will find an unused port to listen on. (In that
- * case, you can use soup_server_get_uris() to find out what port it
- * ended up choosing.)
+ * Attempts to set up @server to listen for connections on "localhost".
  *
- * See soup_server_listen() for more details.
+ * That is, `127.0.0.1` and/or `::1`, depending on whether @options includes
+ * %SOUP_SERVER_LISTEN_IPV4_ONLY, %SOUP_SERVER_LISTEN_IPV6_ONLY, or neither). If
+ * @port is specified, @server will listen on that port. If it is 0, @server
+ * will find an unused port to listen on. (In that case, you can use
+ * [method@Server.get_uris] to find out what port it ended up choosing.
  *
- * Returns: %TRUE on success, %FALSE if @port could not be bound
- * or any other error occurred (in which case @error will be set).
+ * See [method@Server.listen] for more details.
  *
+ * Returns: %TRUE on success, %FALSE if @port could not be bound
+ *   or any other error occurred (in which case @error will be set).
  **/
 gboolean
 soup_server_listen_local (SoupServer *server, guint port,
@@ -1484,14 +1480,12 @@ soup_server_listen_local (SoupServer *server, guint port,
  * @options: listening options for this server
  * @error: return location for a #GError
  *
- * This attempts to set up @server to listen for connections on
- * @socket.
+ * Attempts to set up @server to listen for connections on @socket.
  *
- * See soup_server_listen() for more details.
+ * See [method@Server.listen] for more details.
  *
  * Returns: %TRUE on success, %FALSE if an error occurred (in
- * which case @error will be set).
- *
+ *   which case @error will be set).
  **/
 gboolean
 soup_server_listen_socket (SoupServer *server, GSocket *socket,
@@ -1528,17 +1522,17 @@ soup_server_listen_socket (SoupServer *server, GSocket *socket,
  * @server: a #SoupServer
  *
  * Gets a list of URIs corresponding to the interfaces @server is
- * listening on. These will contain IP addresses, not hostnames, and
- * will also indicate whether the given listener is http or https.
+ * listening on.
  *
- * Note that if you used soup_server_listen_all(), the returned URIs
- * will use the addresses <literal>0.0.0.0</literal> and
- * <literal>::</literal>, rather than actually returning separate URIs
- * for each interface on the system.
+ * These will contain IP addresses, not hostnames, and will also indicate
+ * whether the given listener is http or https.
  *
- * Returns: (transfer full) (element-type GUri): a list of
- * #GUris, which you must free when you are done with it.
+ * Note that if you used [method@Server.listen_all] the returned URIs will use
+ * the addresses `0.0.0.0` and `::`, rather than actually returning separate
+ * URIs for each interface on the system.
  *
+ * Returns: (transfer full) (element-type GUri): a list of #GUris, which you
+ *   must free when you are done with it.
  */
 GSList *
 soup_server_get_uris (SoupServer *server)
@@ -1584,29 +1578,28 @@ soup_server_get_uris (SoupServer *server)
  * @path: the path component of @msg's Request-URI
  * @query: (element-type utf8 utf8) (nullable): the parsed query
  *   component of @msg's Request-URI
- * @user_data: the data passed to soup_server_add_handler() or
- *   soup_server_add_early_handler().
+ * @user_data: the data passed to [method@Server.add_handler] or
+ *   [method@Server.add_early_handler].
  *
- * A callback used to handle requests to a #SoupServer.
+ * A callback used to handle requests to a [class@Server].
  *
  * @path and @query contain the likewise-named components of the
  * Request-URI, subject to certain assumptions. By default,
- * #SoupServer decodes all percent-encoding in the URI path, such that
- * "/foo%<!-- -->2Fbar" is treated the same as "/foo/bar". If your
+ * [class@Server] decodes all percent-encoding in the URI path, such that
+ * `"/foo%2Fbar"` is treated the same as `"/foo/bar"`. If your
  * server is serving resources in some non-POSIX-filesystem namespace,
  * you may want to distinguish those as two distinct paths. In that
- * case, you can set the SoupServer:raw-paths property when creating
- * the #SoupServer, and it will leave those characters undecoded.
- *
- * @query contains the query component of the Request-URI parsed
- * according to the rules for HTML form handling. Although this is the
- * only commonly-used query string format in HTTP, there is nothing
- * that actually requires that HTTP URIs use that format; if your
- * server needs to use some other format, you can just ignore @query,
- * and call soup_message_get_uri() and parse the URI's query field
- * yourself.
- *
- * See soup_server_add_handler() and soup_server_add_early_handler()
+ * case, you can set the [property@Server:raw-paths] property when creating
+ * the [class@Server], and it will leave those characters undecoded.
+ *
+ * @query contains the query component of the Request-URI parsed according to
+ * the rules for HTML form handling. Although this is the only commonly-used
+ * query string format in HTTP, there is nothing that actually requires that
+ * HTTP URIs use that format; if your server needs to use some other format, you
+ * can just ignore @query, and call [method@Message.get_uri] and parse the URI's
+ * query field yourself.
+ *
+ * See [method@Server.add_handler] and [method@Server.add_early_handler]
  * for details of what handlers can/should do.
  **/
 
@@ -1633,45 +1626,44 @@ get_or_create_handler (SoupServer *server, const char *exact_path)
  * soup_server_add_handler:
  * @server: a #SoupServer
  * @path: (nullable): the toplevel path for the handler
- * @callback: (scope notified) (destroy destroy): callback to invoke for requests under @path
+ * @callback: (scope notified) (destroy destroy): callback to invoke for
+ *   requests under @path
  * @user_data: data for @callback
  * @destroy: destroy notifier to free @user_data
  *
- * Adds a handler to @server for requests prefixed by @path. If @path is
- * %NULL or "/", then this will be the default handler for all
- * requests that don't have a more specific handler. (Note though that
- * if you want to handle requests to the special "*" URI, you must
- * explicitly register a handler for "*"; the default handler will not
- * be used for that case.)
+ * Adds a handler to @server for requests prefixed by @path.
+ *
+ * If @path is %NULL or "/", then this will be the default handler for all
+ * requests that don't have a more specific handler. (Note though that if you
+ * want to handle requests to the special "*" URI, you must explicitly register
+ * a handler for "*"; the default handler will not be used for that case.)
  *
  * For requests under @path (that have not already been assigned a
- * status code by a #SoupAuthDomain, an early server handler, or a
+ * status code by a [class@AuthDomain], an early server handler, or a
  * signal handler), @callback will be invoked after receiving the
- * request body; the #SoupServerMessage<!-- -->'s method, request-headers,
+ * request body; the [class@ServerMessage]'s method, request-headers,
  * and request-body properties will be set.
  *
- * After determining what to do with the request, the callback must at
- * a minimum call soup_server_message_set_status() on the message to set the response
- * status code. Additionally, it may set response headers and/or fill
- * in the response body.
+ * After determining what to do with the request, the callback must at a minimum
+ * call [method@ServerMessage.set_status] on the message to set the response
+ * status code. Additionally, it may set response headers and/or fill in the
+ * response body.
  *
  * If the callback cannot fully fill in the response before returning
  * (eg, if it needs to wait for information from a database, or
- * another network server), it should call soup_server_pause_message()
+ * another network server), it should call [method@Server.pause_message]
  * to tell @server to not send the response right away. When the
- * response is ready, call soup_server_unpause_message() to cause it
+ * response is ready, call [method@Server.unpause_message] to cause it
  * to be sent.
  *
- * To send the response body a bit at a time using "chunked" encoding,
- * first call soup_message_headers_set_encoding() to set
- * %SOUP_ENCODING_CHUNKED on the response-headers. Then call
- * soup_message_body_append() (or soup_message_body_append_bytes))
- * to append each chunk as it becomes ready, and
- * soup_server_unpause_message() to make sure it's running. (The
- * server will automatically pause the message if it is using chunked
- * encoding but no more chunks are available.) When you are done, call
- * soup_message_body_complete() to indicate that no more chunks are
- * coming.
+ * To send the response body a bit at a time using "chunked" encoding, first
+ * call [method@MessageHeaders.set_encoding] to set %SOUP_ENCODING_CHUNKED on
+ * the response-headers. Then call [method@MessageBody.append] (or
+ * [method@MessageBody.append_bytes])) to append each chunk as it becomes ready,
+ * and [method@Server.unpause_message] to make sure it's running. (The server
+ * will automatically pause the message if it is using chunked encoding but no
+ * more chunks are available.) When you are done, call
+ * [method@MessageBody.complete] to indicate that no more chunks are coming.
  **/
 void
 soup_server_add_handler (SoupServer            *server,
@@ -1698,38 +1690,37 @@ soup_server_add_handler (SoupServer            *server,
  * soup_server_add_early_handler:
  * @server: a #SoupServer
  * @path: (nullable): the toplevel path for the handler
- * @callback: (scope notified) (destroy destroy): callback to invoke for requests under @path
+ * @callback: (scope notified) (destroy destroy): callback to invoke for
+ *   requests under @path
  * @user_data: data for @callback
  * @destroy: destroy notifier to free @user_data
  *
- * Adds an "early" handler to @server for requests prefixed by @path. Note
- * that "normal" and "early" handlers are matched up together, so if
- * you add a normal handler for "/foo" and an early handler for
- * "/foo/bar", then a request to "/foo/bar" (or any path below it)
- * will run only the early handler. (But if you add both handlers at
- * the same path, then both will get run.)
+ * Adds an "early" handler to @server for requests prefixed by @path.
+ *
+ * Note that "normal" and "early" handlers are matched up together, so if you
+ * add a normal handler for "/foo" and an early handler for "/foo/bar", then a
+ * request to "/foo/bar" (or any path below it) will run only the early handler.
+ * (But if you add both handlers at the same path, then both will get run.)
  *
  * For requests under @path (that have not already been assigned a
- * status code by a #SoupAuthDomain or a signal handler), @callback
+ * status code by a [class@AuthDomain] or a signal handler), @callback
  * will be invoked after receiving the request headers, but before
  * receiving the request body; the message's method and
  * request-headers properties will be set.
  *
- * Early handlers are generally used for processing requests with
- * request bodies in a streaming fashion. If you determine that the
- * request will contain a message body, normally you would call
- * soup_message_body_set_accumulate() on the message's
- * request-body to turn off request-body accumulation,
- * and connect to the message's #SoupServerMessage::got-chunk signal to
- * process each chunk as it comes in.
+ * Early handlers are generally used for processing requests with request bodies
+ * in a streaming fashion. If you determine that the request will contain a
+ * message body, normally you would call [method@MessageBody.set_accumulate] on
+ * the message's request-body to turn off request-body accumulation, and connect
+ * to the message's [signal@ServerMessage::got-chunk] signal to process each
+ * chunk as it comes in.
  *
  * To complete the message processing after the full message body has
- * been read, you can either also connect to #SoupServerMessage::got-body,
+ * been read, you can either also connect to [signal@ServerMessage::got-body],
  * or else you can register a non-early handler for @path as well. As
  * long as you have not set the status-code by the time
- * #SoupServerMessage::got-body is emitted, the non-early handler will be
+ * [signal@ServerMessage::got-body] is emitted, the non-early handler will be
  * run as well.
- *
  **/
 void
 soup_server_add_early_handler (SoupServer            *server,
@@ -1760,13 +1751,13 @@ soup_server_add_early_handler (SoupServer            *server,
  * @msg: the #SoupServerMessage
  * @user_data: the data passed to @soup_server_add_handler
  *
- * A callback used to handle WebSocket requests to a #SoupServer. The
- * callback will be invoked after sending the handshake response back
- * to the client (and is only invoked if the handshake was
- * successful).
+ * A callback used to handle WebSocket requests to a #SoupServer.
+ *
+ * The callback will be invoked after sending the handshake response back to the
+ * client (and is only invoked if the handshake was successful).
  *
  * @path contains the path of the Request-URI, subject to the same
- * rules as #SoupServerCallback (qv).
+ * rules as [callback@ServerCallback] `(qv)`.
  **/
 
 /**
@@ -1776,13 +1767,15 @@ soup_server_add_early_handler (SoupServer            *server,
  * @origin: (nullable): the origin of the connection
  * @protocols: (nullable) (array zero-terminated=1): the protocols
  *   supported by this handler
- * @callback: (scope notified) (destroy destroy): callback to invoke for successful WebSocket requests under @path
+ * @callback: (scope notified) (destroy destroy): callback to invoke for
+ *   successful WebSocket requests under @path
  * @user_data: data for @callback
  * @destroy: destroy notifier to free @user_data
  *
- * Adds a WebSocket handler to @server for requests prefixed by @path. (If
- * @path is %NULL or "/", then this will be the default handler for
- * all requests that don't have a more specific handler.)
+ * Adds a WebSocket handler to @server for requests prefixed by @path.
+ *
+ * If @path is %NULL or "/", then this will be the default handler for all
+ * requests that don't have a more specific handler.
  *
  * When a path has a WebSocket handler registered, @server will check
  * incoming requests for WebSocket handshakes after all other handlers
@@ -1852,15 +1845,15 @@ soup_server_remove_handler (SoupServer *server, const char *path)
  * @server: a #SoupServer
  * @auth_domain: a #SoupAuthDomain
  *
- * Adds an authentication domain to @server. Each auth domain will
- * have the chance to require authentication for each request that
- * comes in; normally auth domains will require authentication for
- * requests on certain paths that they have been set up to watch, or
- * that meet other criteria set by the caller. If an auth domain
- * determines that a request requires authentication (and the request
- * doesn't contain authentication), @server will automatically reject
- * the request with an appropriate status (401 Unauthorized or 407
- * Proxy Authentication Required). If the request used the
+ * Adds an authentication domain to @server.
+ *
+ * Each auth domain will have the chance to require authentication for each
+ * request that comes in; normally auth domains will require authentication for
+ * requests on certain paths that they have been set up to watch, or that meet
+ * other criteria set by the caller. If an auth domain determines that a request
+ * requires authentication (and the request doesn't contain authentication),
+ * @server will automatically reject the request with an appropriate status (401
+ * Unauthorized or 407 Proxy Authentication Required). If the request used the
  * SoupServer:100-continue Expectation, @server will reject it before the
  * request body is sent.
  **/
@@ -1900,13 +1893,16 @@ soup_server_remove_auth_domain (SoupServer *server, SoupAuthDomain *auth_domain)
  * @server: a #SoupServer
  * @msg: a #SoupServerMessage associated with @server.
  *
- * Pauses I/O on @msg. This can be used when you need to return from
- * the server handler without having the full response ready yet. Use
- * soup_server_unpause_message() to resume I/O.
+ * Pauses I/O on @msg.
+ *
+ * This can be used when you need to return from the server handler without
+ * having the full response ready yet. Use [method@Server.unpause_message] to
+ * resume I/O.
  *
- * This must only be called on a #SoupServerMessage which was created by the
+ * This must only be called on a [class@ServerMessage] 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.
+ * [callback@ServerCallback] or emitted in a [signal@Server::request-read]
+ * signal.
  **/
 void
 soup_server_pause_message (SoupServer        *server,
@@ -1923,15 +1919,17 @@ soup_server_pause_message (SoupServer        *server,
  * @server: a #SoupServer
  * @msg: a #SoupServerMessage associated with @server.
  *
- * Resumes I/O on @msg. Use this to resume after calling
- * soup_server_pause_message(), or after adding a new chunk to a
- * chunked response.
+ * Resumes I/O on @msg.
+ *
+ * Use this to resume after calling [method@Server.pause_message], or after
+ * adding a new chunk to a chunked response.
  *
  * I/O won't actually resume until you return to the main loop.
  *
- * This must only be called on a #SoupServerMessage which was created by the
+ * This must only be called on a [class@ServerMessage] 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.
+ * [callback@ServerCallback] or emitted in a [signal@Server::request-read]
+ * signal.
  **/
 void
 soup_server_unpause_message (SoupServer        *server,
@@ -1949,13 +1947,13 @@ soup_server_unpause_message (SoupServer        *server,
  * @extension_type: a #GType
  *
  * Add support for a WebSocket extension of the given @extension_type.
+ *
  * When a WebSocket client requests an extension of @extension_type,
- * a new #SoupWebsocketExtension of type @extension_type will be created
+ * a new [class@WebsocketExtension] of type @extension_type will be created
  * to handle the request.
  *
- * Note that #SoupWebsocketExtensionDeflate is supported by default, use
- * soup_server_remove_websocket_extension() if you want to disable it.
- *
+ * Note that [class@WebsocketExtensionDeflate] is supported by default, use
+ * [method@Server.remove_websocket_extension] if you want to disable it.
  */
 void
 soup_server_add_websocket_extension (SoupServer *server, GType extension_type)
@@ -1980,7 +1978,6 @@ soup_server_add_websocket_extension (SoupServer *server, GType extension_type)
  *
  * Removes support for WebSocket extension of type @extension_type (or any subclass of
  * @extension_type) from @server.
- *
  */
 void
 soup_server_remove_websocket_extension (SoupServer *server, GType extension_type)
diff --git a/libsoup/server/soup-socket.c b/libsoup/server/soup-socket.c
index 2a7c2c50..37a48d14 100644
--- a/libsoup/server/soup-socket.c
+++ b/libsoup/server/soup-socket.c
@@ -310,8 +310,9 @@ soup_socket_class_init (SoupSocketClass *socket_class)
 	 * @sock: the socket
 	 * @new: the new socket
 	 *
-	 * Emitted when a listening socket (set up with
-	 * soup_socket_listen()) receives a new connection.
+	 * Emitted when a listening socket receives a new connection.
+	 *
+	 * Has to be set up with [func@soup_socket_listen].
 	 *
 	 * You must ref the @new if you want to keep it; otherwise it
 	 * will be destroyed after the signal is emitted.
@@ -586,8 +587,9 @@ finish_listener_setup (SoupSocket *sock)
  * @sock: a server #SoupSocket (which must not already be connected or listening)
  * @error: error pointer
  *
- * Makes @sock start listening on its local address. When connections
- * come in, @sock will emit #SoupSocket::new_connection.
+ * Makes @sock start listening on its local address.
+ *
+ * When connections come in, @sock will emit #SoupSocket::new_connection.
  *
  * Returns: whether or not @sock is now listening.
  **/
diff --git a/libsoup/soup-connection.c b/libsoup/soup-connection.c
index 38a91e46..783ede8b 100644
--- a/libsoup/soup-connection.c
+++ b/libsoup/soup-connection.c
@@ -989,7 +989,8 @@ client_message_io_closed_cb (SoupConnection *conn,
  * soup_connection_disconnect:
  * @conn: a connection
  *
- * Disconnects @conn's socket and emits a %disconnected signal.
+ * Disconnects @conn's socket and emits a [signal@Socket::disconnected] signal.
+ *
  * After calling this, @conn will be essentially useless.
  **/
 void
diff --git a/libsoup/soup-date-utils.c b/libsoup/soup-date-utils.c
index 061057ee..fd785f50 100644
--- a/libsoup/soup-date-utils.c
+++ b/libsoup/soup-date-utils.c
@@ -27,15 +27,6 @@
 #include "soup-date-utils-private.h"
 
 /**
- * SECTION:soup-date-utils
- * @section_id: SoupDateTime
- * @title: DateTime Utilities
- * @short_description: Functions to help working with #GDateTime and HTTP
- *
- * These are simple utility functions to help using #GDateTime.
- */
-
-/**
  * soup_date_time_is_past:
  * @date: a #GDateTime
  *
@@ -58,11 +49,11 @@ soup_date_time_is_past (GDateTime *date)
 /**
  * SoupDateFormat:
  * @SOUP_DATE_HTTP: RFC 1123 format, used by the HTTP "Date" header. Eg
- * "Sun, 06 Nov 1994 08:49:37 GMT"
+ *   "Sun, 06 Nov 1994 08:49:37 GMT".
  * @SOUP_DATE_COOKIE: The format for the "Expires" timestamp in the
- * Netscape cookie specification. Eg, "Sun, 06-Nov-1994 08:49:37 GMT".
+ *   Netscape cookie specification. Eg, "Sun, 06-Nov-1994 08:49:37 GMT".
  *
- * Date formats that soup_date_time_to_string() can use.
+ * Date formats that [func@date_time_to_string] can use.
  *
  * @SOUP_DATE_HTTP and @SOUP_DATE_COOKIE always coerce the time to
  * UTC.
@@ -88,7 +79,7 @@ static const char *const days[] = {
  *
  * Converts @date to a string in the format described by @format.
  *
- * Return: (transfer full): @date as a string or %NULL
+ * Returns: (transfer full): @date as a string or %NULL
  **/
 char *
 soup_date_time_to_string (GDateTime      *date,
@@ -307,13 +298,14 @@ parse_textual_date (const char *date_string)
  * soup_date_time_new_from_http_string:
  * @date_string: The date as a string
  *
- * Parses @date_string and tries to extract a date from it. This
- * recognizes all of the "HTTP-date" formats from RFC 2616, RFC 2822
- * dates, and reasonable approximations thereof. (Eg, it is lenient about
- * whitespace, leading "0"s, etc.)
+ * Parses @date_string and tries to extract a date from it.
+ *
+ * This recognizes all of the "HTTP-date" formats from RFC 2616, RFC 2822 dates,
+ * and reasonable approximations thereof. (Eg, it is lenient about whitespace,
+ * leading "0"s, etc.)
  *
  * Returns: (nullable): a new #GDateTime, or %NULL if @date_string
- * could not be parsed.
+ *   could not be parsed.
  **/
 GDateTime *
 soup_date_time_new_from_http_string (const char *date_string)
diff --git a/libsoup/soup-form.c b/libsoup/soup-form.c
index b11dc047..ccce2a8c 100644
--- a/libsoup/soup-form.c
+++ b/libsoup/soup-form.c
@@ -15,31 +15,19 @@
 #include "soup.h"
 
 /**
- * SECTION:soup-form
- * @section_id: SoupForm
- * @short_description: HTML form handling
- * @see_also: #SoupMultipart
- *
- * libsoup contains several help methods for processing HTML forms as
- * defined by the [the HTML 4.01 specification](http://www.w3.org/TR/html401/interact/forms.html#h-17.13).
- **/
-
-/**
  * SOUP_FORM_MIME_TYPE_URLENCODED:
  *
  * A macro containing the value
- * <literal>"application/x-www-form-urlencoded"</literal>; the default
+ * `application/x-www-form-urlencoded`; the default
  * MIME type for POSTing HTML form data.
- *
  **/
 
 /**
  * SOUP_FORM_MIME_TYPE_MULTIPART:
  *
  * A macro containing the value
- * <literal>"multipart/form-data"</literal>; the MIME type used for
+ * `multipart/form-data`; the MIME type used for
  * posting form data that contains files to be uploaded.
- *
  **/
 
 #define XDIGIT(c) ((c) <= '9' ? (c) - '0' : ((c) & 0x4F) - 'A' + 10)
@@ -71,12 +59,13 @@ form_decode (char *part)
  * soup_form_decode:
  * @encoded_form: data of type "application/x-www-form-urlencoded"
  *
- * Decodes @form, which is an urlencoded dataset as defined in the
- * HTML 4.01 spec.
+ * Decodes @form.
+ *
+ * which is an urlencoded dataset as defined in the HTML 4.01 spec.
  *
  * Returns: (element-type utf8 utf8) (transfer container): a hash
- * table containing the name/value pairs from @encoded_form, which you
- * can free with g_hash_table_destroy().
+ *   table containing the name/value pairs from @encoded_form, which you
+ *   can free with [func@GLib.HashTable.destroy].
  **/
 GHashTable *
 soup_form_decode (const char *encoded_form)
@@ -111,35 +100,35 @@ soup_form_decode (const char *encoded_form)
 /**
  * soup_form_decode_multipart:
  * @multipart: a #SoupMultipart
- * @file_control_name: (nullable): the name of the HTML file upload control, or %NULL
- * @filename: (out) (optional): return location for the name of the uploaded file, or %NULL
- * @content_type: (out) (optional): return location for the MIME type of the uploaded file, or %NULL
- * @file: (out) (optional): return location for the uploaded file data, or %NULL
+ * @file_control_name: (nullable): the name of the HTML file upload control
+ * @filename: (out) (optional): return location for the name of the uploaded file
+ * @content_type: (out) (optional): return location for the MIME type of the uploaded file
+ * @file: (out) (optional): return location for the uploaded file data
+ *
+ * Decodes the "multipart/form-data" request in @multipart.
  *
- * Decodes the "multipart/form-data" request in @multipart; this is a
- * convenience method for the case when you have a single file upload
- * control in a form. (Or when you don't have any file upload
- * controls, but are still using "multipart/form-data" anyway.) Pass
- * the name of the file upload control in @file_control_name, and
- * soup_form_decode_multipart() will extract the uploaded file data
- * into @filename, @content_type, and @file. All of the other form
- * control data will be returned (as strings, as with
- * soup_form_decode()) in the returned #GHashTable.
+ * this is a convenience method for the case when you have a single file upload
+ * control in a form. (Or when you don't have any file upload controls, but are
+ * still using "multipart/form-data" anyway.) Pass the name of the file upload
+ * control in @file_control_name, and [func@form_decode_multipart] will extract
+ * the uploaded file data into @filename, @content_type, and @file. All of the
+ * other form control data will be returned (as strings, as with
+ * [func@form_decode] in the returned [struct@GLib.HashTable].
  *
  * You may pass %NULL for @filename, @content_type and/or @file if you do not
- * care about those fields. soup_form_decode_multipart() may also
+ * care about those fields. [func@form_decode_multipart] may also
  * return %NULL in those fields if the client did not provide that
  * information. You must free the returned filename and content-type
- * with g_free(), and the returned file data with g_bytes_unref().
+ * with [func@GLib.free], and the returned file data with [method@Glib.Bytes.unref].
  *
  * If you have a form with more than one file upload control, you will
- * need to decode it manually, using soup_multipart_new_from_message()
- * and soup_multipart_get_part().
+ * need to decode it manually, using [ctor@Multipart.new_from_message]
+ * and [method@Multipart.get_part].
  *
  * Returns: (nullable) (element-type utf8 utf8) (transfer container):
- * a hash table containing the name/value pairs (other than
- * @file_control_name) from @msg, which you can free with
- * g_hash_table_destroy(). On error, it will return %NULL.
+ *   a hash table containing the name/value pairs (other than
+ *   @file_control_name) from @msg, which you can free with
+ *   [func@GLib.HashTable.destroy]. On error, it will return %NULL.
  */
 GHashTable *
 soup_form_decode_multipart (SoupMultipart *multipart,
@@ -234,20 +223,21 @@ encode_pair (GString *str, const char *name, const char *value)
  * soup_form_encode:
  * @first_field: name of the first form field
  * @...: value of @first_field, followed by additional field names
- * and values, terminated by %NULL.
+ *   and values, terminated by %NULL.
  *
  * Encodes the given field names and values into a value of type
- * "application/x-www-form-urlencoded", as defined in the HTML 4.01
- * spec.
+ * "application/x-www-form-urlencoded".
+ *
+ * Encodes as defined in the HTML 4.01 spec.
  *
  * This method requires you to know the names of the form fields (or
  * at the very least, the total number of fields) at compile time; for
- * working with dynamic forms, use soup_form_encode_hash() or
- * soup_form_encode_datalist().
+ * working with dynamic forms, use [func@form_encode_hash] or
+ * [func@form_encode_datalist].
  *
- * Returns: the encoded form
+ * See also: [ctor@Message.new_from_encoded_form].
  *
- * See also: soup_message_new_from_encoded_form()
+ * Returns: the encoded form
  **/
 char *
 soup_form_encode (const char *first_field, ...)
@@ -265,20 +255,21 @@ soup_form_encode (const char *first_field, ...)
 /**
  * soup_form_encode_hash:
  * @form_data_set: (element-type utf8 utf8): a hash table containing
- * name/value pairs (as strings)
+ *   name/value pairs (as strings)
  *
  * Encodes @form_data_set into a value of type
- * "application/x-www-form-urlencoded", as defined in the HTML 4.01
- * spec.
+ * "application/x-www-form-urlencoded".
+ *
+ * Encodes as defined in the HTML 4.01 spec.
  *
  * Note that the HTML spec states that "The control names/values are
  * listed in the order they appear in the document." Since this method
  * takes a hash table, it cannot enforce that; if you care about the
- * ordering of the form fields, use soup_form_encode_datalist().
+ * ordering of the form fields, use [func@form_encode_datalist].
  *
- * Returns: the encoded form
+ * See also: [ctor@Message.new_from_encoded_form].
  *
- * See also: soup_message_new_from_encoded_form()
+ * Returns: the encoded form
  **/
 char *
 soup_form_encode_hash (GHashTable *form_data_set)
@@ -304,13 +295,15 @@ datalist_encode_foreach (GQuark key_id, gpointer value, gpointer str)
  * @form_data_set: a datalist containing name/value pairs
  *
  * Encodes @form_data_set into a value of type
- * "application/x-www-form-urlencoded", as defined in the HTML 4.01
- * spec. Unlike soup_form_encode_hash(), this preserves the ordering
- * of the form elements, which may be required in some situations.
+ * "application/x-www-form-urlencoded".
  *
- * Returns: the encoded form
+ * Encodes as defined in the HTML 4.01 spec. Unlike [func@form_encode_hash],
+ * this preserves the ordering of the form elements, which may be required in
+ * some situations.
  *
- * See also: soup_message_new_from_encoded_form()
+ * See also: [ctor@Message.new_from_encoded_form].
+ *
+ * Returns: the encoded form
  **/
 char *
 soup_form_encode_datalist (GData **form_data_set)
@@ -324,14 +317,16 @@ soup_form_encode_datalist (GData **form_data_set)
 /**
  * soup_form_encode_valist:
  * @first_field: name of the first form field
- * @args: pointer to additional values, as in soup_form_encode()
+ * @args: pointer to additional values, as in [func@form_encode]
  *
- * See soup_form_encode(). This is mostly an internal method, used by
- * various other methods such as soup_form_encode().
+ * See [func@form_encode].
  *
- * Returns: the encoded form
+ * This is mostly an internal method, used by various other methods such as
+ * [func@form_encode].
  *
- * See also: soup_message_new_from_encoded_form()
+ * See also: [ctor@Message.new_from_encoded_form].
+ *
+ * Returns: the encoded form
  **/
 char *
 soup_form_encode_valist (const char *first_field, va_list args)
diff --git a/libsoup/soup-headers.c b/libsoup/soup-headers.c
index 5485e623..8b04a834 100644
--- a/libsoup/soup-headers.c
+++ b/libsoup/soup-headers.c
@@ -18,15 +18,6 @@
 #include "soup.h"
 
 /**
- * SECTION:soup-headers
- * @section_id: SoupHeaders
- * @title: SoupHeaders
- * @short_description: Functions to help working with HTTP Headers
- *
- * These are utility functions to help working with HTTP headers.
- */
-
-/**
  * soup_headers_parse:
  * @str: the header string (including the Request-Line or Status-Line,
  *   but not the trailing blank line)
@@ -34,14 +25,14 @@
  * @dest: #SoupMessageHeaders to store the header values in
  *
  * Parses the headers of an HTTP request or response in @str and
- * stores the results in @dest. Beware that @dest may be modified even
- * on failure.
+ * stores the results in @dest.
+ *
+ * Beware that @dest may be modified even on failure.
  *
  * This is a low-level method; normally you would use
- * soup_headers_parse_request() or soup_headers_parse_response().
+ * [func@headers_parse_request] or [func@headers_parse_response].
  *
  * Returns: success or failure
- *
  **/
 gboolean
 soup_headers_parse (const char *str, int len, SoupMessageHeaders *dest)
@@ -170,11 +161,11 @@ done:
  * @len: length of @str
  * @req_headers: #SoupMessageHeaders to store the header values in
  * @req_method: (out) (optional): if non-%NULL, will be filled in with the
- * request method
+ *   request method
  * @req_path: (out) (optional): if non-%NULL, will be filled in with the
- * request path
+ *   request path
  * @ver: (out) (optional): if non-%NULL, will be filled in with the HTTP
- * version
+ *   version
  *
  * Parses the headers of an HTTP request in @str and stores the
  * results in @req_method, @req_path, @ver, and @req_headers.
@@ -182,7 +173,7 @@ done:
  * Beware that @req_headers may be modified even on failure.
  *
  * Returns: %SOUP_STATUS_OK if the headers could be parsed, or an
- * HTTP error to be returned to the client if they could not be.
+ *   HTTP error to be returned to the client if they could not be.
  **/
 guint
 soup_headers_parse_request (const char          *str, 
@@ -280,15 +271,16 @@ soup_headers_parse_request (const char          *str,
  * soup_headers_parse_status_line:
  * @status_line: an HTTP Status-Line
  * @ver: (out) (optional): if non-%NULL, will be filled in with the HTTP
- * version
+ *   version
  * @status_code: (out) (optional): if non-%NULL, will be filled in with
- * the status code
+ *   the status code
  * @reason_phrase: (out) (optional): if non-%NULL, will be filled in with
- * the reason phrase
+ *   the reason phrase
  *
  * Parses the HTTP Status-Line string in @status_line into @ver,
- * @status_code, and @reason_phrase. @status_line must be terminated by
- * either "\0" or "\r\n".
+ * @status_code, and @reason_phrase.
+ *
+ * @status_line must be terminated by either "\0" or "\r\n".
  *
  * Returns: %TRUE if @status_line was parsed successfully.
  **/
@@ -357,11 +349,11 @@ soup_headers_parse_status_line (const char       *status_line,
  * @len: length of @str
  * @headers: #SoupMessageHeaders to store the header values in
  * @ver: (out) (optional): if non-%NULL, will be filled in with the HTTP
- * version
+ *   version
  * @status_code: (out) (optional): if non-%NULL, will be filled in with
- * the status code
+ *   the status code
  * @reason_phrase: (out) (optional): if non-%NULL, will be filled in with
- * the reason phrase
+ *   the reason phrase
  *
  * Parses the headers of an HTTP response in @str and stores the
  * results in @ver, @status_code, @reason_phrase, and @headers.
@@ -488,12 +480,12 @@ parse_list (const char *header, char delim)
  * soup_header_parse_list:
  * @header: a header value
  *
- * Parses a header whose content is described by RFC2616 as
- * "#something", where "something" does not itself contain commas,
- * except as part of quoted-strings.
+ * Parses a header whose content is described by RFC2616 as `#something`.
+ *
+ * "something" does not itself contain commas, except as part of quoted-strings.
  *
  * Returns: (transfer full) (element-type utf8): a #GSList of
- * list elements, as allocated strings
+ *   list elements, as allocated strings
  **/
 GSList *
 soup_header_parse_list (const char *header)
@@ -526,7 +518,7 @@ sort_by_qval (const void *a, const void *b)
  * soup_header_parse_quality_list:
  * @header: a header value
  * @unacceptable: (out) (optional) (transfer full) (element-type utf8): on
- * return, will contain a list of unacceptable values
+ *   return, will contain a list of unacceptable values
  *
  * Parses a header whose content is a list of items with optional
  * "qvalue"s (eg, Accept, Accept-Charset, Accept-Encoding,
@@ -537,7 +529,7 @@ sort_by_qval (const void *a, const void *b)
  * the main list.
  *
  * Returns: (transfer full) (element-type utf8): a #GSList of
- * acceptable values (as allocated strings), highest-qvalue first.
+ *   acceptable values (as allocated strings), highest-qvalue first.
  **/
 GSList *
 soup_header_parse_quality_list (const char *header, GSList **unacceptable)
@@ -613,8 +605,8 @@ soup_header_parse_quality_list (const char *header, GSList **unacceptable)
 
 /**
  * soup_header_free_list: (skip)
- * @list: a #GSList returned from soup_header_parse_list() or
- * soup_header_parse_quality_list()
+ * @list: a #GSList returned from [func@header_parse_list] or
+ * [func@header_parse_quality_list]
  *
  * Frees @list.
  **/
@@ -627,12 +619,13 @@ soup_header_free_list (GSList *list)
 /**
  * soup_header_contains:
  * @header: An HTTP header suitable for parsing with
- * soup_header_parse_list()
+ *   [func@header_parse_list]
  * @token: a token
  *
  * Parses @header to see if it contains the token @token (matched
- * case-insensitively). Note that this can't be used with lists
- * that have qvalues.
+ * case-insensitively).
+ *
+ * Note that this can't be used with lists that have qvalues.
  *
  * Returns: whether or not @header contains @token
  **/
@@ -786,7 +779,7 @@ parse_param_list (const char *header, char delim, gboolean strict)
  * @header: a header value
  *
  * Parses a header which is a comma-delimited list of something like:
- * <literal>token [ "=" ( token | quoted-string ) ]</literal>.
+ * `token [ "=" ( token | quoted-string ) ]`.
  *
  * Tokens that don't have an associated value will still be added to
  * the resulting hash table, but with a %NULL value.
@@ -796,8 +789,8 @@ parse_param_list (const char *header, char delim, gboolean strict)
  * header).
  *
  * Returns: (element-type utf8 utf8) (transfer full): a
- * #GHashTable of list elements, which can be freed with
- * soup_header_free_param_list().
+ *   #GHashTable of list elements, which can be freed with
+ *   [func@header_free_param_list].
  **/
 GHashTable *
 soup_header_parse_param_list (const char *header)
@@ -812,7 +805,7 @@ soup_header_parse_param_list (const char *header)
  * @header: a header value
  *
  * Parses a header which is a semicolon-delimited list of something
- * like: <literal>token [ "=" ( token | quoted-string ) ]</literal>.
+ * like: `token [ "=" ( token | quoted-string ) ]`.
  *
  * Tokens that don't have an associated value will still be added to
  * the resulting hash table, but with a %NULL value.
@@ -822,9 +815,8 @@ soup_header_parse_param_list (const char *header)
  * header).
  *
  * Returns: (element-type utf8 utf8) (transfer full): a
- * #GHashTable of list elements, which can be freed with
- * soup_header_free_param_list().
- *
+ *   #GHashTable of list elements, which can be freed with
+ *   [func@header_free_param_list].
  **/
 GHashTable *
 soup_header_parse_semi_param_list (const char *header)
@@ -838,19 +830,19 @@ soup_header_parse_semi_param_list (const char *header)
  * soup_header_parse_param_list_strict:
  * @header: a header value
  *
- * A strict version of soup_header_parse_param_list()
+ * A strict version of [func@header_parse_param_list]
  * that bails out if there are duplicate parameters.
+ *
  * Note that this function will treat RFC5987-encoded
  * parameters as duplicated if an ASCII version is also
  * present. For header fields that might contain
  * RFC5987-encoded parameters, use
- * soup_header_parse_param_list() instead.
+ * [func@header_parse_param_list] instead.
  *
  * Returns: (element-type utf8 utf8) (transfer full) (nullable):
- * a #GHashTable of list elements, which can be freed with
- * soup_header_free_param_list() or %NULL if there are duplicate
- * elements.
- *
+ *   a #GHashTable of list elements, which can be freed with
+ *   [func@header_free_param_list] or %NULL if there are duplicate
+ *   elements.
  **/
 GHashTable *
 soup_header_parse_param_list_strict (const char *header)
@@ -864,19 +856,19 @@ soup_header_parse_param_list_strict (const char *header)
  * soup_header_parse_semi_param_list_strict:
  * @header: a header value
  *
- * A strict version of soup_header_parse_semi_param_list()
+ * A strict version of [func@header_parse_semi_param_list]
  * that bails out if there are duplicate parameters.
+ *
  * Note that this function will treat RFC5987-encoded
  * parameters as duplicated if an ASCII version is also
  * present. For header fields that might contain
  * RFC5987-encoded parameters, use
- * soup_header_parse_semi_param_list() instead.
+ * [func@header_parse_semi_param_list] instead.
  *
  * Returns: (element-type utf8 utf8) (transfer full) (nullable):
- * a #GHashTable of list elements, which can be freed with
- * soup_header_free_param_list() or %NULL if there are duplicate
- * elements.
- *
+ *   a #GHashTable of list elements, which can be freed with
+ *   [func@header_free_param_list] or %NULL if there are duplicate
+ *   elements.
  **/
 GHashTable *
 soup_header_parse_semi_param_list_strict (const char *header)
@@ -888,8 +880,8 @@ soup_header_parse_semi_param_list_strict (const char *header)
 
 /**
  * soup_header_free_param_list:
- * @param_list: (element-type utf8 utf8): a #GHashTable returned from soup_header_parse_param_list()
- * or soup_header_parse_semi_param_list()
+ * @param_list: (element-type utf8 utf8): a #GHashTable returned from
+ *   [func@header_parse_param_list] or [func@header_parse_semi_param_list]
  *
  * Frees @param_list.
  **/
@@ -972,12 +964,11 @@ append_param_internal (GString    *string,
  * @name: a parameter name
  * @value: a parameter value
  *
- * Appends something like <literal>@name="@value"</literal> to
+ * Appends something like `name="value"` to
  * @string, taking care to escape any quotes or backslashes in @value.
  *
  * If @value is (non-ASCII) UTF-8, this will instead use RFC 5987
- * encoding, just like soup_header_g_string_append_param().
- *
+ * encoding, just like [func@header_g_string_append_param].
  **/
 void
 soup_header_g_string_append_param_quoted (GString    *string,
@@ -997,9 +988,8 @@ soup_header_g_string_append_param_quoted (GString    *string,
  * @name: a parameter name
  * @value: a parameter value, or %NULL
  *
- * Appends something like <literal>@name=@value</literal> to @string,
- * taking care to quote @value if needed, and if so, to escape any
- * quotes or backslashes in @value.
+ * Appends something like `name=value` to @string, taking care to quote @value
+ * if needed, and if so, to escape any quotes or backslashes in @value.
  *
  * Alternatively, if @value is a non-ASCII UTF-8 string, it will be
  * appended using RFC5987 syntax. Although in theory this is supposed
@@ -1008,7 +998,6 @@ soup_header_g_string_append_param_quoted (GString    *string,
  * "filename" parameter.
  *
  * If @value is %NULL, this will just append @name to @string.
- *
  **/
 void
 soup_header_g_string_append_param (GString    *string,
diff --git a/libsoup/soup-logger.c b/libsoup/soup-logger.c
index 9f6f080c..e7b2bdb4 100644
--- a/libsoup/soup-logger.c
+++ b/libsoup/soup-logger.c
@@ -23,24 +23,25 @@
 #include "soup-session-feature-private.h"
 
 /**
- * SECTION:soup-logger
- * @short_description: Debug logging support
+ * SoupLogger:
+ *
+ * Debug logging support
  *
- * #SoupLogger watches a #SoupSession and logs the HTTP traffic that
+ * #SoupLogger watches a [class@Session] and logs the HTTP traffic that
  * it generates, for debugging purposes. Many applications use an
  * environment variable to determine whether or not to use
  * #SoupLogger, and to determine the amount of debugging output.
  *
- * To use #SoupLogger, first create a logger with soup_logger_new(),
- * optionally configure it with soup_logger_set_request_filter(),
- * soup_logger_set_response_filter(), and soup_logger_set_printer(),
- * and then attach it to a session (or multiple sessions) with
- * soup_session_add_feature().
+ * To use #SoupLogger, first create a logger with [ctor@Logger.new], optionally
+ * configure it with [method@Logger.set_request_filter],
+ * [method@Logger.set_response_filter], and [method@Logger.set_printer], and
+ * then attach it to a session (or multiple sessions) with
+ * [method@Session.add_feature].
  *
- * By default, the debugging output is sent to
- * <literal>stdout</literal>, and looks something like:
+ * By default, the debugging output is sent to `stdout`, and looks something
+ * like:
  *
- * <informalexample><screen>
+ * ```
  * > POST /unauth HTTP/1.1
  * > Soup-Debug-Timestamp: 1200171744
  * > Soup-Debug: SoupSession 1 (0x612190), SoupMessage 1 (0x617000), GSocket 1 (0x612220)
@@ -53,45 +54,36 @@
  * &lt; Soup-Debug: SoupMessage 1 (0x617000)
  * &lt; Date: Sun, 12 Jan 2008 21:02:24 GMT
  * &lt; Content-Length: 0
- * </screen></informalexample>
+ * ```
  *
- * The <literal>Soup-Debug-Timestamp</literal> line gives the time (as
- * a <type>time_t</type>) when the request was sent, or the response fully
- * received.
+ * The `Soup-Debug-Timestamp` line gives the time (as a `time_t`) when the
+ * request was sent, or the response fully received.
  *
- * The <literal>Soup-Debug</literal> line gives further debugging
- * information about the #SoupSession, #SoupMessage, and #GSocket
- * involved; the hex numbers are the addresses of the objects in
- * question (which may be useful if you are running in a debugger).
- * The decimal IDs are simply counters that uniquely identify objects
- * across the lifetime of the #SoupLogger. In particular, this can be
- * used to identify when multiple messages are sent across the same
- * connection.
+ * The `Soup-Debug` line gives further debugging information about the
+ * [class@Session], [class@Message], and [class@Gio.Socket] involved; the hex
+ * numbers are the addresses of the objects in question (which may be useful if
+ * you are running in a debugger). The decimal IDs are simply counters that
+ * uniquely identify objects across the lifetime of the #SoupLogger. In
+ * particular, this can be used to identify when multiple messages are sent
+ * across the same connection.
  *
  * Currently, the request half of the message is logged just before
  * the first byte of the request gets written to the network (from the
- * #SoupMessage::starting signal).
- *
- * The response is logged just after the last byte of the response
- * body is read from the network (from the #SoupMessage::got-body or
- * #SoupMessage::got-informational signal), which means that the
- * #SoupMessage::got-headers signal, and anything triggered off it
- * (such as #SoupMessage::authenticate) will be emitted
- * <emphasis>before</emphasis> the response headers are actually
- * logged.
- *
- * If the response doesn't happen to trigger the
- * #SoupMessage::got-body nor #SoupMessage::got-informational signals
- * due to, for example, a cancellation before receiving the last byte
- * of the response body, the response will still be logged on the
- * event of the #SoupMessage::finished signal.
- **/
-
-/**
- * SoupLogger:
+ * [signal@Message::starting] signal).
  *
- * Class implementing logging.
- */
+ * The response is logged just after the last byte of the response body is read
+ * from the network (from the [signal@Message::got-body] or
+ * [signal@Message::got-informational] signal), which means that the
+ * [signal@Message::got-headers] signal, and anything triggered off it (such as
+ * #SoupMessage::authenticate) will be emitted *before* the response headers are
+ * actually logged.
+ *
+ * If the response doesn't happen to trigger the [signal@Message::got-body] nor
+ * [signal@Message::got-informational] signals due to, for example, a
+ * cancellation before receiving the last byte of the response body, the
+ * response will still be logged on the event of the [signal@Message::finished]
+ * signal.
+ **/
 
 struct _SoupLogger {
 	GObject parent;
@@ -341,8 +333,7 @@ soup_logger_class_init (SoupLoggerClass *logger_class)
 	/**
 	 * SoupLogger:level:
 	 *
-	 * The level of logging output
-	 *
+	 * The level of logging output.
 	 */
         properties[PROP_LEVEL] =
 		g_param_spec_enum ("level",
@@ -353,12 +344,11 @@ soup_logger_class_init (SoupLoggerClass *logger_class)
 				    G_PARAM_READWRITE |
 				    G_PARAM_STATIC_STRINGS);
 	/**
-	 * SoupLogger:max-body-size:
+	 * SoupLogger:max-body-size: (attributes org.gtk.Property.get=soup_logger_get_max_body_size org.gtk.Property.set=soup_logger_set_max_body_size)
 	 *
-	 * If #SoupLogger:level is %SOUP_LOGGER_LOG_BODY, this gives
+	 * If [property@Logger:level] is %SOUP_LOGGER_LOG_BODY, this gives
 	 * the maximum number of bytes of the body that will be logged.
 	 * (-1 means "no limit".)
-	 *
 	 **/
         properties[PROP_MAX_BODY_SIZE] =
 		g_param_spec_int ("max-body-size",
@@ -378,7 +368,7 @@ soup_logger_class_init (SoupLoggerClass *logger_class)
  * SoupLoggerLogLevel:
  * @SOUP_LOGGER_LOG_NONE: No logging
  * @SOUP_LOGGER_LOG_MINIMAL: Log the Request-Line or Status-Line and
- * the Soup-Debug pseudo-headers
+ *   the Soup-Debug pseudo-headers
  * @SOUP_LOGGER_LOG_HEADERS: Log the full request/response headers
  * @SOUP_LOGGER_LOG_BODY: Log the full headers and request/response bodies
  *
@@ -392,8 +382,8 @@ soup_logger_class_init (SoupLoggerClass *logger_class)
  * Creates a new #SoupLogger with the given debug level.
  *
  * If you need finer control over what message parts are and aren't
- * logged, use soup_logger_set_request_filter() and
- * soup_logger_set_response_filter().
+ * logged, use [method@Logger.set_request_filter] and
+ * [method@Logger.set_response_filter].
  *
  * Returns: a new #SoupLogger
  **/
@@ -407,16 +397,17 @@ soup_logger_new (SoupLoggerLogLevel level)
  * SoupLoggerFilter:
  * @logger: the #SoupLogger
  * @msg: the message being logged
- * @user_data: the data passed to soup_logger_set_request_filter()
- * or soup_logger_set_response_filter()
+ * @user_data: the data passed to [method@Logger.set_request_filter]
+ *   or [method@Logger.set_response_filter]
  *
- * The prototype for a logging filter. The filter callback will be
- * invoked for each request or response, and should analyze it and
- * return a #SoupLoggerLogLevel value indicating how much of the
- * message to log.
+ * The prototype for a logging filter.
  *
- * Returns: a #SoupLoggerLogLevel value indicating how much of
- * the message to log
+ * The filter callback will be invoked for each request or response, and should
+ * analyze it and return a [enum@LoggerLogLevel] value indicating how much of
+ * the message to log.
+ *
+ * Returns: a [enum@LoggerLogLevel] value indicating how much of the message to
+ *   log
  **/
 
 /**
@@ -427,10 +418,11 @@ soup_logger_new (SoupLoggerLogLevel level)
  * @destroy: a #GDestroyNotify to free @filter_data
  *
  * Sets up a filter to determine the log level for a given request.
+ *
  * For each HTTP request @logger will invoke @request_filter to
  * determine how much (if any) of that request to log. (If you do not
  * set a request filter, @logger will just always log requests at the
- * level passed to soup_logger_new().)
+ * level passed to [ctor@Logger.new].)
  **/
 void
 soup_logger_set_request_filter (SoupLogger       *logger,
@@ -453,10 +445,11 @@ soup_logger_set_request_filter (SoupLogger       *logger,
  * @destroy: a #GDestroyNotify to free @filter_data
  *
  * Sets up a filter to determine the log level for a given response.
+ *
  * For each HTTP response @logger will invoke @response_filter to
  * determine how much (if any) of that response to log. (If you do not
  * set a response filter, @logger will just always log responses at
- * the level passed to soup_logger_new().)
+ * the level passed to [ctor@Logger.new].)
  **/
 void
 soup_logger_set_response_filter (SoupLogger       *logger,
@@ -477,7 +470,7 @@ soup_logger_set_response_filter (SoupLogger       *logger,
  * @level: the level of the information being printed.
  * @direction: a single-character prefix to @data
  * @data: data to print
- * @user_data: the data passed to soup_logger_set_printer()
+ * @user_data: the data passed to [method@Logger.set_printer]
  *
  * The prototype for a custom printing callback.
  *
@@ -489,9 +482,9 @@ soup_logger_set_response_filter (SoupLogger       *logger,
  *
  * To get the effect of the default printer, you would do:
  *
- * <informalexample><programlisting>
- *	printf ("%c %s\n", direction, data);
- * </programlisting></informalexample>
+ * ```c
+ * printf ("%c %s\n", direction, data);
+ * ```
  **/
 
 /**
@@ -502,7 +495,7 @@ soup_logger_set_response_filter (SoupLogger       *logger,
  * @destroy: a #GDestroyNotify to free @printer_data
  *
  * Sets up an alternate log printing routine, if you don't want
- * the log to go to <literal>stdout</literal>.
+ * the log to go to `stdout`.
  **/
 void
 soup_logger_set_printer (SoupLogger        *logger,
@@ -518,7 +511,7 @@ soup_logger_set_printer (SoupLogger        *logger,
 }
 
 /**
- * soup_logger_set_max_body_size:
+ * soup_logger_set_max_body_size: (attributes org.gtk.Method.set_property=max-body-size)
  * @logger: a #SoupLogger
  * @max_body_size: the maximum body size to log
  *
@@ -533,7 +526,7 @@ soup_logger_set_max_body_size (SoupLogger *logger, int max_body_size)
 }
 
 /**
- * soup_logger_get_max_body_size:
+ * soup_logger_get_max_body_size: (attributes org.gtk.Method.get_property=max-body-size)
  * @logger: a #SoupLogger
  *
  * Get the maximum body size for @logger.
diff --git a/libsoup/soup-message-headers.c b/libsoup/soup-message-headers.c
index 29d7966d..bcee5b98 100644
--- a/libsoup/soup-message-headers.c
+++ b/libsoup/soup-message-headers.c
@@ -16,15 +16,6 @@
 #include "soup-misc.h"
 
 /**
- * SECTION:soup-message-headers
- * @short_description: HTTP message headers
- * @see_also: #SoupMessage
- *
- * #SoupMessageHeaders represents the HTTP message headers associated
- * with a request or response.
- **/
-
-/**
  * SoupMessageHeaders:
  *
  * The HTTP message headers associated with a request or response.
@@ -36,7 +27,7 @@
  * @SOUP_MESSAGE_HEADERS_RESPONSE: response headers
  * @SOUP_MESSAGE_HEADERS_MULTIPART: multipart body part headers
  *
- * Value passed to soup_message_headers_new() to set certain default
+ * Value passed to [ctor@MessageHeaders.new] to set certain default
  * behaviors.
  **/
 
@@ -71,9 +62,11 @@ struct _SoupMessageHeaders {
  * soup_message_headers_new:
  * @type: the type of headers
  *
- * Creates a #SoupMessageHeaders. (#SoupMessage does this
- * automatically for its own headers. You would only need to use this
- * method if you are manually parsing or generating message headers.)
+ * Creates a #SoupMessageHeaders.
+ *
+ * ([class@Message] does this automatically for its own headers. You would only
+ * need to use this method if you are manually parsing or generating message
+ * headers.)
  *
  * Returns: a new #SoupMessageHeaders
  **/
@@ -122,6 +115,7 @@ soup_message_headers_destroy (SoupMessageHeaders *hdrs)
  * @hdrs: a #SoupMessageHeaders
  *
  * Atomically decrements the reference count of @hdrs by one.
+ *
  * When the reference count reaches zero, the resources allocated by
  * @hdrs are freed
  */
@@ -140,7 +134,6 @@ G_DEFINE_BOXED_TYPE (SoupMessageHeaders, soup_message_headers, soup_message_head
  * Gets the type of headers.
  *
  * Returns: the header's type.
- *
  **/
 SoupMessageHeadersType
 soup_message_headers_get_headers_type (SoupMessageHeaders *hdrs)
@@ -256,7 +249,6 @@ soup_message_headers_clear (SoupMessageHeaders *hdrs)
  * @hdrs: a #SoupMessageHeaders
  *
  * Removes all the headers listed in the Connection header.
- *
  */
 void
 soup_message_headers_clean_connection_headers (SoupMessageHeaders *hdrs)
@@ -300,10 +292,11 @@ soup_message_headers_append_common (SoupMessageHeaders *hdrs,
  * @name: the header name to add
  * @value: the new value of @name
  *
- * Appends a new header with name @name and value @value to @hdrs. (If
- * there is an existing header with name @name, then this creates a
- * second one, which is only allowed for list-valued headers; see also
- * soup_message_headers_replace().)
+ * Appends a new header with name @name and value @value to @hdrs.
+ *
+ * (If there is an existing header with name @name, then this creates a second
+ * one, which is only allowed for list-valued headers; see also
+ * [method@MessageHeaders.replace].)
  *
  * The caller is expected to make sure that @name and @value are
  * syntactically correct.
@@ -383,8 +376,9 @@ soup_message_headers_replace_common (SoupMessageHeaders *hdrs,
  * @name: the header name to replace
  * @value: the new value of @name
  *
- * Replaces the value of the header @name in @hdrs with @value. (See
- * also soup_message_headers_append().)
+ * Replaces the value of the header @name in @hdrs with @value.
+ *
+ * See also [method@MessageHeaders.append].
  *
  * The caller is expected to make sure that @name and @value are
  * syntactically correct.
@@ -493,8 +487,9 @@ soup_message_headers_remove_common (SoupMessageHeaders *hdrs,
  * @hdrs: a #SoupMessageHeaders
  * @name: the header name to remove
  *
- * Removes @name from @hdrs. If there are multiple values for @name,
- * they are all removed.
+ * Removes @name from @hdrs.
+ *
+ * If there are multiple values for @name, they are all removed.
  **/
 void
 soup_message_headers_remove (SoupMessageHeaders *hdrs, const char *name)
@@ -547,10 +542,11 @@ soup_message_headers_get_one_common (SoupMessageHeaders *hdrs,
  * @hdrs: a #SoupMessageHeaders
  * @name: (in): header name
  * 
- * Gets the value of header @name in @hdrs. Use this for headers whose
- * values are <emphasis>not</emphasis> comma-delimited lists, and
- * which therefore can only appear at most once in the headers. For
- * list-valued headers, use soup_message_headers_get_list().
+ * Gets the value of header @name in @hdrs.
+ *
+ * Use this for headers whose values are *not* comma-delimited lists, and which
+ * therefore can only appear at most once in the headers. For list-valued
+ * headers, use [method@MessageHeaders.get_list].
  *
  * If @hdrs does erroneously contain multiple copies of the header, it
  * is not defined which one will be returned. (Ideally, it will return
@@ -558,7 +554,6 @@ soup_message_headers_get_one_common (SoupMessageHeaders *hdrs,
  * implementations.)
  *
  * Returns: (nullable) (transfer none): the header's value or %NULL if not found.
- *
  **/
 const char *
 soup_message_headers_get_one (SoupMessageHeaders *hdrs, const char *name)
@@ -603,11 +598,10 @@ soup_message_headers_header_contains_common (SoupMessageHeaders *hdrs,
  * and contains a case-insensitive match for @token.
  *
  * (If @name is present in @hdrs, then this is equivalent to calling
- * soup_header_contains() on its value.)
+ * [func@header_contains] on its value.)
  *
  * Returns: %TRUE if the header is present and contains @token,
  *   %FALSE otherwise.
- *
  **/
 gboolean
 soup_message_headers_header_contains (SoupMessageHeaders *hdrs, const char *name, const char *token)
@@ -642,7 +636,6 @@ soup_message_headers_header_equals_common (SoupMessageHeaders *hdrs,
  *
  * Returns: %TRUE if the header is present and its value is
  *   @value, %FALSE otherwise.
- *
  **/
 gboolean
 soup_message_headers_header_equals (SoupMessageHeaders *hdrs, const char *name, const char *value)
@@ -700,13 +693,14 @@ soup_message_headers_get_list_common (SoupMessageHeaders *hdrs,
  * @hdrs: a #SoupMessageHeaders
  * @name: header name
  * 
- * Gets the value of header @name in @hdrs. Use this for headers whose
- * values are comma-delimited lists, and which are therefore allowed
- * to appear multiple times in the headers. For non-list-valued
- * headers, use soup_message_headers_get_one().
+ * Gets the value of header @name in @hdrs.
+ *
+ * Use this for headers whose values are comma-delimited lists, and which are
+ * therefore allowed to appear multiple times in the headers. For
+ * non-list-valued headers, use [method@MessageHeaders.get_one].
  *
  * If @name appears multiple times in @hdrs,
- * soup_message_headers_get_list() will concatenate all of the values
+ * [method@MessageHeaders.get_list] will concatenate all of the values
  * together, separated by commas. This is sometimes awkward to parse
  * (eg, WWW-Authenticate, Set-Cookie), but you have to be able to deal
  * with it anyway, because the HTTP spec explicitly states that this
@@ -714,7 +708,6 @@ soup_message_headers_get_list_common (SoupMessageHeaders *hdrs,
  * same thing.
  * 
  * Returns: (nullable) (transfer none): the header's value or %NULL if not found.
- *
  **/
 const char *
 soup_message_headers_get_list (SoupMessageHeaders *hdrs, const char *name)
@@ -770,9 +763,8 @@ soup_message_headers_get_list (SoupMessageHeaders *hdrs, const char *name)
  * An opaque type used to iterate over a %SoupMessageHeaders
  * structure.
  *
- * After intializing the iterator with
- * soup_message_headers_iter_init(), call
- * soup_message_headers_iter_next() to fetch data from it.
+ * After intializing the iterator with [func@MessageHeadersIter.init], call
+ * [method@MessageHeadersIter.next] to fetch data from it.
  *
  * You may not modify the headers while iterating over them.
  **/
@@ -786,7 +778,7 @@ typedef struct {
 /**
  * soup_message_headers_iter_init:
  * @iter: (out) (transfer none): a pointer to a %SoupMessageHeadersIter
- * structure
+ *   structure
  * @hdrs: a %SoupMessageHeaders
  *
  * Initializes @iter for iterating @hdrs.
@@ -806,17 +798,19 @@ soup_message_headers_iter_init (SoupMessageHeadersIter *iter,
  * soup_message_headers_iter_next:
  * @iter: (inout) (transfer none): a %SoupMessageHeadersIter
  * @name: (out) (transfer none): pointer to a variable to return
- * the header name in
+ *   the header name in
  * @value: (out) (transfer none): pointer to a variable to return
- * the header value in
+ *   the header value in
  *
- * Yields the next name/value pair in the %SoupMessageHeaders being
- * iterated by @iter. If @iter has already yielded the last header,
- * then soup_message_headers_iter_next() will return %FALSE and @name
- * and @value will be unchanged.
+ * Yields the next name/value pair in the [struct@MessageHeaders] being
+ * iterated by @iter.
+ *
+ * If @iter has already yielded the last header, then
+ * [method@MessageHeadersIter.next] will return %FALSE and @name and @value
+ * will be unchanged.
  *
  * Returns: %TRUE if another name and value were returned, %FALSE
- * if the end of the headers has been reached.
+ *   if the end of the headers has been reached.
  **/
 gboolean
 soup_message_headers_iter_next (SoupMessageHeadersIter *iter,
@@ -851,9 +845,9 @@ soup_message_headers_iter_next (SoupMessageHeadersIter *iter,
  * SoupMessageHeadersForeachFunc:
  * @name: the header name
  * @value: the header value
- * @user_data: the data passed to soup_message_headers_foreach()
+ * @user_data: the data passed to [method@MessageHeaders.foreach]
  *
- * The callback passed to soup_message_headers_foreach().
+ * The callback passed to [method@MessageHeaders.foreach].
  **/
 
 /**
@@ -864,11 +858,11 @@ soup_message_headers_iter_next (SoupMessageHeadersIter *iter,
  * 
  * Calls @func once for each header value in @hdrs.
  *
- * Beware that unlike soup_message_headers_get_list(), this processes the
+ * Beware that unlike [method@MessageHeaders.get_list], this processes the
  * headers in exactly the way they were added, rather than
  * concatenating multiple same-named headers into a single value.
  * (This is intentional; it ensures that if you call
- * soup_message_headers_append() multiple times with the same name,
+ * [method@MessageHeaders.append] multiple times with the same name,
  * then the I/O code will output multiple copies of the header when
  * sending the message to the remote implementation, which may be
  * required for interoperability in some cases.)
@@ -903,13 +897,13 @@ soup_message_headers_foreach (SoupMessageHeaders           *hdrs,
  * SoupEncoding:
  * @SOUP_ENCODING_UNRECOGNIZED: unknown / error
  * @SOUP_ENCODING_NONE: no body is present (which is not the same as a
- * 0-length body, and only occurs in certain places)
+ *   0-length body, and only occurs in certain places)
  * @SOUP_ENCODING_CONTENT_LENGTH: Content-Length encoding
  * @SOUP_ENCODING_EOF: Response body ends when the connection is closed
  * @SOUP_ENCODING_CHUNKED: chunked encoding (currently only supported
- * for response)
+ *   for response)
  * @SOUP_ENCODING_BYTERANGES: multipart/byteranges (Reserved for future
- * use: NOT CURRENTLY IMPLEMENTED)
+ *   use: NOT CURRENTLY IMPLEMENTED)
  *
  * How a message body is encoded for transport
  **/
@@ -918,10 +912,11 @@ soup_message_headers_foreach (SoupMessageHeaders           *hdrs,
  * soup_message_headers_get_encoding:
  * @hdrs: a #SoupMessageHeaders
  *
- * Gets the message body encoding that @hdrs declare. This may not
- * always correspond to the encoding used on the wire; eg, a HEAD
- * response may declare a Content-Length or Transfer-Encoding, but
- * it will never actually include a body.
+ * Gets the message body encoding that @hdrs declare.
+ *
+ * This may not always correspond to the encoding used on the wire; eg, a HEAD
+ * response may declare a Content-Length or Transfer-Encoding, but it will never
+ * actually include a body.
  *
  * Returns: the encoding declared by @hdrs.
  **/
@@ -960,9 +955,10 @@ soup_message_headers_get_encoding (SoupMessageHeaders *hdrs)
  * @hdrs: a #SoupMessageHeaders
  * @encoding: a #SoupEncoding
  *
- * Sets the message body encoding that @hdrs will declare. In particular,
- * you should use this if you are going to send a request or response in
- * chunked encoding.
+ * Sets the message body encoding that @hdrs will declare.
+ *
+ * In particular, you should use this if you are going to send a request or
+ * response in chunked encoding.
  **/
 void
 soup_message_headers_set_encoding (SoupMessageHeaders *hdrs,
@@ -998,8 +994,9 @@ soup_message_headers_set_encoding (SoupMessageHeaders *hdrs,
  * soup_message_headers_get_content_length:
  * @hdrs: a #SoupMessageHeaders
  *
- * Gets the message body length that @hdrs declare. This will only
- * be non-0 if soup_message_headers_get_encoding() returns
+ * Gets the message body length that @hdrs declare.
+ *
+ * This will only be non-0 if [method@MessageHeaders.get_encoding] returns
  * %SOUP_ENCODING_CONTENT_LENGTH.
  *
  * Returns: the message body length declared by @hdrs.
@@ -1029,7 +1026,7 @@ soup_message_headers_get_content_length (SoupMessageHeaders *hdrs)
  * Content-Length header for you immediately before sending the
  * headers. One situation in which this method is useful is when
  * generating the response to a HEAD request; Calling
- * soup_message_headers_set_content_length() allows you to put the
+ * [method@MessageHeaders.set_content_length] allows you to put the
  * correct content length into the response without needing to waste
  * memory by filling in a response body which won't actually be sent.
  **/
@@ -1058,6 +1055,7 @@ soup_message_headers_set_content_length (SoupMessageHeaders *hdrs,
  * @hdrs: a #SoupMessageHeaders
  *
  * Gets the expectations declared by @hdrs's "Expect" header.
+ *
  * Currently this will either be %SOUP_EXPECTATION_CONTINUE or
  * %SOUP_EXPECTATION_UNRECOGNIZED.
  *
@@ -1116,7 +1114,6 @@ soup_message_headers_set_expectations (SoupMessageHeaders *hdrs,
  * If @end is -1 and @start is negative, then it represents a "suffix
  * range", referring to the last -@start bytes of the resource body.
  * (Eg, the last 500 bytes would be @start = -500 and @end = -1.)
- *
  **/
 
 static int
@@ -1229,24 +1226,24 @@ soup_message_headers_get_ranges_internal (SoupMessageHeaders  *hdrs,
  * @hdrs: a #SoupMessageHeaders
  * @total_length: the total_length of the response body
  * @ranges: (out) (array length=length): return location for an array
- * of #SoupRange
+ *   of #SoupRange
  * @length: the length of the returned array
  *
  * Parses @hdrs's Range header and returns an array of the requested
- * byte ranges. The returned array must be freed with
- * soup_message_headers_free_ranges().
+ * byte ranges.
+ *
+ * The returned array must be freed with [method@MessageHeaders.free_ranges].
  *
  * If @total_length is non-0, its value will be used to adjust the
  * returned ranges to have explicit start and end values, and the
  * returned ranges will be sorted and non-overlapping. If
  * @total_length is 0, then some ranges may have an end value of -1,
- * as described under #SoupRange, and some of the ranges may be
+ * as described under [struct@Range], and some of the ranges may be
  * redundant.
  *
  * Beware that even if given a @total_length, this function does not
  * check that the ranges are satisfiable.
  *
- * <note><para>
  * #SoupServer has built-in handling for range requests. If your
  * server handler returns a %SOUP_STATUS_OK response containing the
  * complete response body (rather than pausing the message and
@@ -1260,12 +1257,10 @@ soup_message_headers_get_ranges_internal (SoupMessageHeaders  *hdrs,
  * it all at once, or you do not already have the complete response
  * body available, and only want to generate the parts that were
  * actually requested by the client.
- * </para></note>
  *
  * Returns: %TRUE if @hdrs contained a syntactically-valid
- * "Range" header, %FALSE otherwise (in which case @range and @length
- * will not be set).
- *
+ *   "Range" header, %FALSE otherwise (in which case @range and @length
+ *   will not be set).
  **/
 gboolean
 soup_message_headers_get_ranges (SoupMessageHeaders  *hdrs,
@@ -1284,8 +1279,7 @@ soup_message_headers_get_ranges (SoupMessageHeaders  *hdrs,
  * @hdrs: a #SoupMessageHeaders
  * @ranges: an array of #SoupRange
  *
- * Frees the array of ranges returned from soup_message_headers_get_ranges().
- *
+ * Frees the array of ranges returned from [method@MessageHeaders.get_ranges].
  **/
 void
 soup_message_headers_free_ranges (SoupMessageHeaders  *hdrs,
@@ -1300,10 +1294,10 @@ soup_message_headers_free_ranges (SoupMessageHeaders  *hdrs,
  * @ranges: an array of #SoupRange
  * @length: the length of @range
  *
- * Sets @hdrs's Range header to request the indicated ranges. (If you
- * only want to request a single range, you can use
- * soup_message_headers_set_range().)
+ * Sets @hdrs's Range header to request the indicated ranges.
  *
+ * If you only want to request a single range, you can use
+ * [method@MessageHeaders.set_range].
  **/
 void
 soup_message_headers_set_ranges (SoupMessageHeaders  *hdrs,
@@ -1340,11 +1334,11 @@ soup_message_headers_set_ranges (SoupMessageHeaders  *hdrs,
  * @end: the end of the range to request
  *
  * Sets @hdrs's Range header to request the indicated range.
- * @start and @end are interpreted as in a #SoupRange.
  *
- * If you need to request multiple ranges, use
- * soup_message_headers_set_ranges().
+ * @start and @end are interpreted as in a [struct@Range].
  *
+ * If you need to request multiple ranges, use
+ * [method@MessageHeaders.set_ranges].
  **/
 void
 soup_message_headers_set_range (SoupMessageHeaders  *hdrs,
@@ -1364,15 +1358,14 @@ soup_message_headers_set_range (SoupMessageHeaders  *hdrs,
  * @start: (out): return value for the start of the range
  * @end: (out): return value for the end of the range
  * @total_length: (out) (optional): return value for the total length of the
- * resource, or %NULL if you don't care.
+ *   resource, or %NULL if you don't care.
  *
  * Parses @hdrs's Content-Range header and returns it in @start,
  * @end, and @total_length. If the total length field in the header
  * was specified as "*", then @total_length will be set to -1.
  *
  * Returns: %TRUE if @hdrs contained a "Content-Range" header
- * containing a byte range which could be parsed, %FALSE otherwise.
- *
+ *   containing a byte range which could be parsed, %FALSE otherwise.
  **/
 gboolean
 soup_message_headers_get_content_range (SoupMessageHeaders  *hdrs,
@@ -1419,15 +1412,13 @@ soup_message_headers_get_content_range (SoupMessageHeaders  *hdrs,
  * @total_length: the total length of the resource, or -1 if unknown
  *
  * Sets @hdrs's Content-Range header according to the given values.
+ *
  * (Note that @total_length is the total length of the entire resource
  * that this is a range of, not simply @end - @start + 1.)
  *
- * <note><para>
- * #SoupServer has built-in handling for range requests, and you do
+ * [class@Server] has built-in handling for range requests, and you do
  * not normally need to call this function youself. See
- * soup_message_headers_get_ranges() for more details.
- * </para></note>
- *
+ * [method@MessageHeaders.get_ranges] for more details.
  **/
 void
 soup_message_headers_set_content_range (SoupMessageHeaders  *hdrs,
@@ -1532,14 +1523,14 @@ set_content_foo (SoupMessageHeaders *hdrs,
  *   %NULL
  *
  * Looks up the "Content-Type" header in @hdrs, parses it, and returns
- * its value in *@content_type and *@params. @params can be %NULL if you
- * are only interested in the content type itself.
+ * its value in *@content_type and *@params.
  *
- * Returns: (nullable): a string with the value of the
- * "Content-Type" header or %NULL if @hdrs does not contain that
- * header or it cannot be parsed (in which case *@params will be
- * unchanged).
+ * @params can be %NULL if you are only interested in the content type itself.
  *
+ * Returns: (nullable): a string with the value of the
+ *   "Content-Type" header or %NULL if @hdrs does not contain that
+ *   header or it cannot be parsed (in which case *@params will be
+ *   unchanged).
  **/
 const char *
 soup_message_headers_get_content_type (SoupMessageHeaders  *hdrs,
@@ -1557,12 +1548,11 @@ soup_message_headers_get_content_type (SoupMessageHeaders  *hdrs,
  * soup_message_headers_set_content_type:
  * @hdrs: a #SoupMessageHeaders
  * @content_type: the MIME type
- * @params: (nullable) (element-type utf8 utf8): additional
- * parameters, or %NULL
+ * @params: (nullable) (element-type utf8 utf8): additional parameters
  *
- * Sets the "Content-Type" header in @hdrs to @content_type,
- * optionally with additional parameters specified in @params.
+ * Sets the "Content-Type" header in @hdrs to @content_type.
  *
+ * Accepts additional parameters specified in @params.
  **/
 void
 soup_message_headers_set_content_type (SoupMessageHeaders  *hdrs,
@@ -1576,13 +1566,14 @@ soup_message_headers_set_content_type (SoupMessageHeaders  *hdrs,
  * soup_message_headers_get_content_disposition:
  * @hdrs: a #SoupMessageHeaders
  * @disposition: (out) (transfer full): return location for the
- * disposition-type, or %NULL
+ *   disposition-type, or %NULL
  * @params: (out) (transfer full) (element-type utf8 utf8): return
- * location for the Content-Disposition parameters, or %NULL
+ *   location for the Content-Disposition parameters, or %NULL
  *
  * Looks up the "Content-Disposition" header in @hdrs, parses it, and
- * returns its value in *@disposition and *@params. @params can be
- * %NULL if you are only interested in the disposition-type.
+ * returns its value in *@disposition and *@params.
+ *
+ * @params can be %NULL if you are only interested in the disposition-type.
  *
  * In HTTP, the most common use of this header is to set a
  * disposition-type of "attachment", to suggest to the browser that a
@@ -1594,13 +1585,12 @@ soup_message_headers_set_content_type (SoupMessageHeaders  *hdrs,
  * test this yourself.)
  *
  * Content-Disposition is also used in "multipart/form-data", however
- * this is handled automatically by #SoupMultipart and the associated
+ * this is handled automatically by [struct@Multipart] and the associated
  * form methods.
  *
  * Returns: %TRUE if @hdrs contains a "Content-Disposition"
- * header, %FALSE if not (in which case *@disposition and *@params
- * will be unchanged).
- *
+ *   header, %FALSE if not (in which case *@disposition and *@params
+ *   will be unchanged).
  **/
 gboolean
 soup_message_headers_get_content_disposition (SoupMessageHeaders  *hdrs,
@@ -1630,15 +1620,13 @@ soup_message_headers_get_content_disposition (SoupMessageHeaders  *hdrs,
  * soup_message_headers_set_content_disposition:
  * @hdrs: a #SoupMessageHeaders
  * @disposition: the disposition-type
- * @params: (nullable) (element-type utf8 utf8): additional
- * parameters, or %NULL
+ * @params: (nullable) (element-type utf8 utf8): additional parameters
  *
  * Sets the "Content-Disposition" header in @hdrs to @disposition,
  * optionally with additional parameters specified in @params.
  *
- * See soup_message_headers_get_content_disposition() for a discussion
+ * See [method@MessageHeaders.get_content_disposition] for a discussion
  * of how Content-Disposition is used in HTTP.
- *
  **/
 void
 soup_message_headers_set_content_disposition (SoupMessageHeaders  *hdrs,
diff --git a/libsoup/soup-message-metrics.c b/libsoup/soup-message-metrics.c
index 41a9ef49..a308dadc 100644
--- a/libsoup/soup-message-metrics.c
+++ b/libsoup/soup-message-metrics.c
@@ -12,29 +12,21 @@
 #include "soup-message-metrics-private.h"
 
 /**
- * SECTION:soup-message-metrics
- * @short_description: Message metrics
- * @see_also: #SoupMessage
+ * SoupMessageMetrics:
  *
- * Metrics collected while loading a #SoupMessage.
+ * Contains metrics collected while loading a [class@Message] either from the
+ * network or the disk cache.
  *
- * Metrics are not collected by default for a #SoupMessage, you need to add the
+ * Metrics are not collected by default for a [class@Message], you need to add the
  * flag %SOUP_MESSAGE_COLLECT_METRICS to enable the feature.
- */
-
-/**
- * SoupMessageMetrics:
- *
- * SoupMessageMetrics contains metrics collected while loading a #SoupMessage
- * either from the network or the disk cache.
  *
  * Temporal metrics are expressed as a monotonic time and always start with a
  * fetch start event and finish with response end. All other events are optional.
  * An event can be 0 because it hasn't happened yet, because it's optional or
  * because the load failed before the event reached.
  *
- * Size metrics are expressed in bytes and aree updated while the #SoupMessage is
- * being loaded. You can connect to different #SoupMessage signals to get the
+ * Size metrics are expressed in bytes and aree updated while the [class@Message] is
+ * being loaded. You can connect to different [class@Message] signals to get the
  * final result of every value.
  */
 
@@ -53,7 +45,6 @@ soup_message_metrics_new (void)
  * Copies @metrics.
  *
  * Returns: a copy of @metrics
- *
  **/
 SoupMessageMetrics *
 soup_message_metrics_copy (SoupMessageMetrics *metrics)
@@ -72,7 +63,7 @@ soup_message_metrics_copy (SoupMessageMetrics *metrics)
  * soup_message_metrics_free:
  * @metrics: a #SoupMessageMetrics
  *
- * Frees @metrics
+ * Frees @metrics.
  */
 void
 soup_message_metrics_free (SoupMessageMetrics *metrics)
@@ -86,7 +77,7 @@ soup_message_metrics_free (SoupMessageMetrics *metrics)
  * soup_message_metrics_get_fetch_start:
  * @metrics: a #SoupMessageMetrics
  *
- * Get the time immediately before the #SoupMessage started to
+ * Get the time immediately before the [class@Message] started to
  * fetch a resource either from a remote server or local disk cache.
  *
  * Returns: the fetch start time
@@ -103,10 +94,12 @@ soup_message_metrics_get_fetch_start (SoupMessageMetrics *metrics)
  * soup_message_metrics_get_dns_start:
  * @metrics: a #SoupMessageMetrics
  *
- * Get the time immediately before the #SoupMessage started the
- * domain lookup name for the resource. It will be 0 if no domain
- * lookup was required to fetch the resource (a persistent connection
- * was used or resource was loaded from the local disk cache).
+ * Get the time immediately before the [class@Message] started the
+ * domain lookup name for the resource.
+ *
+ * It will be 0 if no domain lookup was required to fetch the resource (a
+ * persistent connection was used or resource was loaded from the local disk
+ * cache).
  *
  * Returns: the domain lookup start time
  */
@@ -122,10 +115,12 @@ soup_message_metrics_get_dns_start (SoupMessageMetrics *metrics)
  * soup_message_metrics_get_dns_end:
  * @metrics: a #SoupMessageMetrics
  *
- * Get the time immediately after the #SoupMessage completed the
- * domain lookup name for the resource. It will be 0 if no domain
- * lookup was required to fetch the resource (a persistent connection
- * was used or resource was loaded from the local disk cache).
+ * Get the time immediately after the [class@Message] completed the
+ * domain lookup name for the resource.
+ *
+ * It will be 0 if no domain lookup was required to fetch the resource (a
+ * persistent connection was used or resource was loaded from the local disk
+ * cache).
  *
  * Returns: the domain lookup end time
  */
@@ -141,10 +136,12 @@ soup_message_metrics_get_dns_end (SoupMessageMetrics *metrics)
  * soup_message_metrics_get_connect_start:
  * @metrics: a #SoupMessageMetrics
  *
- * Get the time immediately before the #SoupMessage started to
- * establish the connection to the server. It will be 0 if no
- * network connection was required to fetch the resource (a persistent
- * connection was used or resource was loaded from the local disk cache).
+ * Get the time immediately before the [class@Message] started to
+ * establish the connection to the server.
+ *
+ * It will be 0 if no network connection was required to fetch the resource (a
+ * persistent connection was used or resource was loaded from the local disk
+ * cache).
  *
  * Returns: the connection start time
  */
@@ -160,11 +157,13 @@ soup_message_metrics_get_connect_start (SoupMessageMetrics *metrics)
  * soup_message_metrics_get_connect_end:
  * @metrics: a #SoupMessageMetrics
  *
- * Get the time immediately after the #SoupMessage completed the
+ * Get the time immediately after the [class@Message] completed the
  * connection to the server. This includes the time for the proxy
- * negotiation and TLS handshake. It will be 0 if no network connection
- * was required to fetch the resource (a persistent connection was used
- * or resource was loaded from the local disk cache).
+ * negotiation and TLS handshake.
+ *
+ * It will be 0 if no network connection was required to fetch the resource (a
+ * persistent connection was used or resource was loaded from the local disk
+ * cache).
  *
  * Returns: the connection end time
  */
@@ -180,10 +179,12 @@ soup_message_metrics_get_connect_end (SoupMessageMetrics *metrics)
  * soup_message_metrics_get_tls_start:
  * @metrics: a #SoupMessageMetrics
  *
- * Get the time immediately before the #SoupMessage started the
- * TLS handshake. It will be 0 if no TLS handshake was required
- * to fetch the resource (connection was not secure, a persistent
- * connection was used or resource was loaded from the local disk cache).
+ * Get the time immediately before the [class@Message] started the
+ * TLS handshake.
+ *
+ * It will be 0 if no TLS handshake was required to fetch the resource
+ * (connection was not secure, a persistent connection was used or resource was
+ * loaded from the local disk cache).
  *
  * Returns: the tls start time
  */
@@ -199,7 +200,7 @@ soup_message_metrics_get_tls_start (SoupMessageMetrics *metrics)
  * soup_message_metrics_get_request_start:
  * @metrics: a #SoupMessageMetrics
  *
- * Get the time immediately before the #SoupMessage started the
+ * Get the time immediately before the [class@Message] started the
  * request of the resource from the server or the local disk cache.
  *
  * Returns: the request start time
@@ -216,7 +217,7 @@ soup_message_metrics_get_request_start (SoupMessageMetrics *metrics)
  * soup_message_metrics_get_response_start:
  * @metrics: a #SoupMessageMetrics
  *
- * Get the time immediately after the #SoupMessage received the first
+ * Get the time immediately after the [class@Message] received the first
  * bytes of the response from the server or the local disk cache.
  *
  * Returns: the response start time
@@ -233,8 +234,9 @@ soup_message_metrics_get_response_start (SoupMessageMetrics *metrics)
  * soup_message_metrics_get_response_end:
  * @metrics: a #SoupMessageMetrics
  *
- * Get the time immediately after the #SoupMessage received the last
+ * Get the time immediately after the [class@Message] received the last
  * bytes of the response from the server or the local disk cache.
+ *
  * In case of load failure, this returns the time immediately before the
  * fetch is aborted.
  *
@@ -253,7 +255,8 @@ soup_message_metrics_get_response_end (SoupMessageMetrics *metrics)
  * @metrics: a #SoupMessageMetrics
  *
  * Get the number of bytes sent to the network for the request headers.
- * This value is available right before #SoupMessage::wrote-headers signal
+ *
+ * This value is available right before [signal@Message::wrote-headers] signal
  * is emitted, but you might get an intermediate value if called before.
  *
  * Returns: the request headers bytes sent
@@ -271,9 +274,10 @@ soup_message_metrics_get_request_header_bytes_sent (SoupMessageMetrics *metrics)
  * @metrics: a #SoupMessageMetrics
  *
  * Get the request body size in bytes. This is the size of the original body
- * given to the request before any encoding is applied. This value is available
- * right before #SoupMessage::wrote-body signal is emitted, but you might get
- * an intermediate value if called before.
+ * given to the request before any encoding is applied.
+ *
+ * This value is available right before [signal@Message::wrote-body] signal is
+ * emitted, but you might get an intermediate value if called before.
  *
  * Returns: the request body size
  */
@@ -289,11 +293,13 @@ soup_message_metrics_get_request_body_size (SoupMessageMetrics *metrics)
  * soup_message_metrics_get_request_body_bytes_sent:
  * @metrics: a #SoupMessageMetrics
  *
- * Get the number of bytes sent to the network for the request body. This is
- * the size of the body sent, after encodings are applied, so it might be
- * greater than the value returned by soup_message_metrics_get_request_body_size().
- * This value is available right before #SoupMessage::wrote-body signal is
- * emitted, but you might get an intermediate value if called before.
+ * Get the number of bytes sent to the network for the request body.
+ *
+ * This is the size of the body sent, after encodings are applied, so it might
+ * be greater than the value returned by
+ * [method@MessageMetrics.get_request_body_size]. This value is available right
+ * before [signal@Message::wrote-body] signal is emitted, but you might get an
+ * intermediate value if called before.
  *
  * Returns: the request body bytes sent
  */
@@ -310,7 +316,8 @@ soup_message_metrics_get_request_body_bytes_sent (SoupMessageMetrics *metrics)
  * @metrics: a #SoupMessageMetrics
  *
  * Get the number of bytes received from the network for the response headers.
- * This value is available right before #SoupMessage::got-headers signal
+ *
+ * This value is available right before [signal@Message::got-headers] signal
  * is emitted, but you might get an intermediate value if called before.
  * For resources loaded from the disk cache this value is always 0.
  *
@@ -328,11 +335,13 @@ soup_message_metrics_get_response_header_bytes_received (SoupMessageMetrics *met
  * soup_message_metrics_get_response_body_size:
  * @metrics: a #SoupMessageMetrics
  *
- * Get the response body size in bytes. This is the size of the body as given to the
- * user after all encodings are applied, so it might be greater than the value
- * returned by soup_message_metrics_get_response_body_bytes_received(). This value is
- * available right before #SoupMessage::got-body signal is emitted, but you might get
- * an intermediate value if called before.
+ * Get the response body size in bytes.
+ *
+ * This is the size of the body as given to the user after all encodings are
+ * applied, so it might be greater than the value returned by
+ * [method@MessageMetrics.get_response_body_bytes_received]. This value is
+ * available right before [signal@Message::got-body] signal is emitted, but you
+ * might get an intermediate value if called before.
  *
  * Returns: the response body size
  */
@@ -348,10 +357,11 @@ soup_message_metrics_get_response_body_size (SoupMessageMetrics *metrics)
  * soup_message_metrics_get_response_body_bytes_received:
  * @metrics: a #SoupMessageMetrics
  *
- * Get the number of bytes received from the network for the response body. This value is
- * available right before #SoupMessage::got-body signal is emitted, but you might get
- * an intermediate value if called before.
- * For resources loaded from the disk cache this value is always 0.
+ * Get the number of bytes received from the network for the response body.
+ *
+ * This value is available right before [signal@Message::got-body] signal is
+ * emitted, but you might get an intermediate value if called before. For
+ * resources loaded from the disk cache this value is always 0.
  *
  * Returns: the response body bytes received
  */
diff --git a/libsoup/soup-message.c b/libsoup/soup-message.c
index 73671819..ad408b11 100644
--- a/libsoup/soup-message.c
+++ b/libsoup/soup-message.c
@@ -21,39 +21,30 @@
 #include "content-sniffer/soup-content-sniffer-stream.h"
 
 /**
- * SECTION:soup-message
- * @short_description: An HTTP request and response.
- * @see_also: #SoupMessageHeaders
+ * SoupMessage:
+ *
+ * Represents an HTTP message being sent or received.
  *
  * A #SoupMessage represents an HTTP message that is being sent or
  * received.
  *
- * You would create a #SoupMessage with soup_message_new() or
- * soup_message_new_from_uri(), set up its
- * fields appropriately, and send it.
- *
- * Note that libsoup's terminology here does not quite match the HTTP
- * specification: in RFC 2616, an "HTTP-message" is
- * <emphasis>either</emphasis> a Request, <emphasis>or</emphasis> a
- * Response. In libsoup, a #SoupMessage combines both the request and
- * the response.
- **/
-
-/**
- * SoupMessage:
+ * You would create a #SoupMessage with [ctor@Message.new] or
+ * [ctor@Message.new_from_uri], set up its fields appropriately, and send it.
  *
- * Represents an HTTP message being sent or received.
+ * [property@Message:status-code] will normally be a [enum@Status] value, eg,
+ * %SOUP_STATUS_OK, though of course it might actually be an unknown status
+ * code. [property@Message:reason-phrase] is the actual text returned from the
+ * server, which may or may not correspond to the "standard" description of
+ * @status_code. At any rate, it is almost certainly not localized, and not very
+ * descriptive even if it is in the user's language; you should not use
+ * [property@Message:reason-phrase] in user-visible messages. Rather, you should
+ * look at [property@Message:status-code], and determine an end-user-appropriate
+ * message based on that and on what you were trying to do.
  *
- * @status_code will normally be a #SoupStatus value, eg,
- * %SOUP_STATUS_OK, though of course it might actually be an unknown
- * status code. @reason_phrase is the actual text returned from the
- * server, which may or may not correspond to the "standard"
- * description of @status_code. At any rate, it is almost certainly
- * not localized, and not very descriptive even if it is in the user's
- * language; you should not use @reason_phrase in user-visible
- * messages. Rather, you should look at @status_code, and determine an
- * end-user-appropriate message based on that and on what you were
- * trying to do.
+ * Note that libsoup's terminology here does not quite match the HTTP
+ * specification: in RFC 2616, an "HTTP-message" is *either* a Request, *or* a
+ * Response. In libsoup, a #SoupMessage combines both the request and the
+ * response.
  */
 
 struct _SoupMessage {
@@ -362,7 +353,6 @@ soup_message_class_init (SoupMessageClass *message_class)
 	 *
 	 * Emitted immediately after writing a portion of the message
 	 * body to the network.
-	 *
 	 **/
 	signals[WROTE_BODY_DATA] =
 		g_signal_new ("wrote-body-data",
@@ -395,10 +385,11 @@ soup_message_class_init (SoupMessageClass *message_class)
 	 * @msg: the message
 	 *
 	 * Emitted after receiving a 1xx (Informational) response for
-	 * a (client-side) message. The response_headers will be
-	 * filled in with the headers associated with the
-	 * informational response; however, those header values will
-	 * be erased after this signal is done.
+	 * a (client-side) message.
+	 *
+	 * The response_headers will be filled in with the headers associated
+	 * with the informational response; however, those header values will be
+	 * erased after this signal is done.
 	 *
 	 * If you cancel or requeue @msg while processing this signal,
 	 * then the current HTTP I/O will be stopped after this signal
@@ -419,17 +410,17 @@ soup_message_class_init (SoupMessageClass *message_class)
 	 *
 	 * Emitted after receiving the Status-Line and response headers.
 	 *
-	 * See also soup_message_add_header_handler() and
-	 * soup_message_add_status_code_handler(), which can be used
-	 * to connect to a subset of emissions of this signal.
+	 * See also [method@Message.add_header_handler] and
+	 * [method@Message.add_status_code_handler], which can be used to
+	 * connect to a subset of emissions of this signal.
 	 *
 	 * If you cancel or requeue @msg while processing this signal,
 	 * then the current HTTP I/O will be stopped after this signal
 	 * emission finished, and @msg's connection will be closed.
 	 * (If you need to requeue a message--eg, after handling
 	 * authentication or redirection--it is usually better to
-	 * requeue it from a #SoupMessage::got_body handler rather
-	 * than a #SoupMessage::got_headers handler, so that the
+	 * requeue it from a [signal@Message::got-body] handler rather
+	 * than a [signal@Message::got_headers] handler, so that the
 	 * existing HTTP connection can be reused.)
 	 **/
 	signals[GOT_HEADERS] =
@@ -447,8 +438,8 @@ soup_message_class_init (SoupMessageClass *message_class)
 	 *
 	 * Emitted after receiving the complete message request body.
 	 *
-	 * See also soup_message_add_header_handler() and
-	 * soup_message_add_status_code_handler(), which can be used
+	 * See also [method@Message.add_header_handler] and
+	 * [method@Message.add_status_code_handler], which can be used
 	 * to connect to a subset of emissions of this signal.
 	 **/
 	signals[GOT_BODY] =
@@ -466,13 +457,13 @@ soup_message_class_init (SoupMessageClass *message_class)
 	 * @type: the content type that we got from sniffing
 	 * @params: (element-type utf8 utf8): a #GHashTable with the parameters
 	 *
-	 * This signal is emitted after #SoupMessage::got-headers.
+	 * This signal is emitted after [signal@Message::got-headers].
+	 *
 	 * If content sniffing is disabled, or no content sniffing will be
 	 * performed, due to the sniffer deciding to trust the
 	 * Content-Type sent by the server, this signal is emitted
-	 * immediately after #SoupMessage::got-headers, and @type is
+	 * immediately after [signal@Message::got-headers], and @type is
 	 * %NULL.
-	 *
 	 **/
 	signals[CONTENT_SNIFFED] =
 		g_signal_new ("content-sniffed",
@@ -490,7 +481,6 @@ soup_message_class_init (SoupMessageClass *message_class)
 	 * @msg: the message
 	 *
 	 * Emitted just before a message is sent.
-	 *
 	 */
 	signals[STARTING] =
 		g_signal_new ("starting",
@@ -506,9 +496,11 @@ soup_message_class_init (SoupMessageClass *message_class)
 	 * @msg: the message
 	 *
 	 * Emitted when a request that was already sent once is now
-	 * being sent again (eg, because the first attempt received a
+	 * being sent again.
+	 *
+	 * e.g. because the first attempt received a
 	 * redirection response, or because we needed to use
-	 * authentication).
+	 * authentication.
 	 **/
 	signals[RESTARTED] =
 		g_signal_new ("restarted",
@@ -524,7 +516,8 @@ soup_message_class_init (SoupMessageClass *message_class)
 	 * @msg: the message
 	 *
 	 * Emitted when all HTTP processing is finished for a message.
-	 * (After #SoupMessage::got_body).
+	 *
+	 * (After [signal@Message::got_body]).
 	 **/
 	signals[FINISHED] =
 		g_signal_new ("finished",
@@ -541,22 +534,23 @@ soup_message_class_init (SoupMessageClass *message_class)
 	 * @auth: the #SoupAuth to authenticate
 	 * @retrying: %TRUE if this is the second (or later) attempt
 	 *
-	 * Emitted when the message requires authentication. If
-	 * credentials are available call soup_auth_authenticate() on
-	 * @auth. If these credentials fail, the signal will be
-	 * emitted again, with @retrying set to %TRUE, which will
-	 * continue until you return without calling
-	 * soup_auth_authenticate() on @auth.
+	 * Emitted when the message requires authentication.
+	 *
+	 * If credentials are available call [method@Auth.authenticate] on
+	 * @auth. If these credentials fail, the signal will be emitted again,
+	 * with @retrying set to %TRUE, which will continue until you return
+	 * without calling [method@Auth.authenticate] on @auth.
 	 *
 	 * Note that this may be emitted before @msg's body has been
 	 * fully read.
 	 *
-	 * You can authenticate @auth asynchronously by calling g_object_ref()
-	 * on @auth and returning %TRUE. The operation will complete once
-	 * either soup_auth_authenticate() or soup_auth_cancel() are called.
+	 * You can authenticate @auth asynchronously by calling
+	 * [method@GObject.Object.ref] on @auth and returning %TRUE. The operation will
+	 * complete once either [method@Auth.authenticate] or
+	 * [method@Auth.cancel] are called.
 	 *
 	 * Returns: %TRUE to stop other handlers from being invoked
-	 *    or %FALSE to propagate the event further.
+	 *   or %FALSE to propagate the event further.
 	 **/
 	signals[AUTHENTICATE] =
 		g_signal_new ("authenticate",
@@ -576,18 +570,17 @@ soup_message_class_init (SoupMessageClass *message_class)
 	 * @connection: the current state of the network connection
 	 *
 	 * Emitted to indicate that some network-related event
-	 * related to @msg has occurred. This essentially proxies the
-	 * #GSocketClient::event signal, but only for events that
-	 * occur while @msg "owns" the connection; if @msg is sent on
-	 * an existing persistent connection, then this signal will
-	 * not be emitted. (If you want to force the message to be
-	 * sent on a new connection, set the
-	 * %SOUP_MESSAGE_NEW_CONNECTION flag on it.)
+	 * related to @msg has occurred.
+	 *
+	 * This essentially proxies the [signal@Gio.SocketClient::event] signal,
+	 * but only for events that occur while @msg "owns" the connection; if
+	 * @msg is sent on an existing persistent connection, then this signal
+	 * will not be emitted. (If you want to force the message to be sent on
+	 * a new connection, set the %SOUP_MESSAGE_NEW_CONNECTION flag on it.)
 	 *
-	 * See #GSocketClient::event for more information on what
+	 * See [signal@Gio.SocketClient::event] for more information on what
 	 * the different values of @event correspond to, and what
 	 * @connection will be in each case.
-	 *
 	 **/
 	signals[NETWORK_EVENT] =
 		g_signal_new ("network-event",
@@ -608,12 +601,13 @@ soup_message_class_init (SoupMessageClass *message_class)
 	 *
 	 * Emitted during the @msg's connection TLS handshake
 	 * after an unacceptable TLS certificate has been received.
+	 *
 	 * You can return %TRUE to accept @tls_certificate despite
 	 * @tls_errors.
 	 *
 	 * Returns: %TRUE to accept the TLS certificate and stop other
-	 *     handlers from being invoked, or %FALSE to propagate the
-	 *     event further.
+	 *   handlers from being invoked, or %FALSE to propagate the
+	 *   event further.
 	 */
 	signals[ACCEPT_CERTIFICATE] =
 		g_signal_new ("accept-certificate",
@@ -633,17 +627,18 @@ soup_message_class_init (SoupMessageClass *message_class)
          *
          * Emitted during the @msg's connection TLS handshake when
          * @tls_connection requests a certificate from the client.
+         *
          * You can set the client certificate by calling
-         * soup_message_set_tls_client_certificate() and returning %TRUE.
-         * It's possible to handle the request asynchornously by returning
-         * %TRUE and call soup_message_set_tls_client_certificate() later
-         * once the certificate is available.
-         * Note that this signal is not emitted if #SoupSession::tls-interaction
-         * was set, or if soup_message_set_tls_client_certificate() was called
-         * before the connection TLS handshake started.
+         * [method@Message.set_tls_client_certificate] and returning %TRUE. It's
+         * possible to handle the request asynchornously by returning %TRUE and
+         * call [method@Message.set_tls_client_certificate] later once the
+         * certificate is available. Note that this signal is not emitted if
+         * [property@Session:tls-interaction] was set, or if
+         * [method@Message.set_tls_client_certificate] was called before the
+         * connection TLS handshake started.
          *
          * Returns: %TRUE to handle the request, or %FALSE to make the connection
-         *     fail with %G_TLS_ERROR_CERTIFICATE_REQUIRED.
+         *   fail with %G_TLS_ERROR_CERTIFICATE_REQUIRED.
          */
         signals[REQUEST_CERTIFICATE] =
                 g_signal_new ("request-certificate",
@@ -662,18 +657,19 @@ soup_message_class_init (SoupMessageClass *message_class)
          *
          * Emitted during the @msg's connection TLS handshake when
          * @tls_connection requests a certificate password from the client.
+         *
          * You can set the certificate password on @password, then call
-         * soup_message_tls_client_certificate_password_request_complete() and return %TRUE
-         * to handle the signal synchronously.
-         * It's possible to handle the request asynchornously by calling g_object_ref()
-         * on @password, then returning %TRUE and call
-         * soup_message_tls_client_certificate_password_request_complete() later after
-         * setting the password on @password.
-         * Note that this signal is not emitted if #SoupSession::tls-interaction
-         * was set.
+         * [method@Message.tls_client_certificate_password_request_complete] and
+         * return %TRUE to handle the signal synchronously. It's possible to
+         * handle the request asynchornously by calling
+         * [method@GObject.Object.ref] on @password, then returning %TRUE and
+         * call
+         * [method@Message.tls_client_certificate_password_request_complete]
+         * later after setting the password on @password. Note that this signal
+         * is not emitted if [property@Session:tls-interaction] was set.
          *
          * Returns: %TRUE to handle the request, or %FALSE to make the connection
-         *     fail with %G_TLS_ERROR_CERTIFICATE_REQUIRED.
+         *   fail with %G_TLS_ERROR_CERTIFICATE_REQUIRED.
          */
         signals[REQUEST_CERTIFICATE_PASSWORD] =
                 g_signal_new ("request-certificate-password",
@@ -689,7 +685,7 @@ soup_message_class_init (SoupMessageClass *message_class)
 	 * SoupMessage::hsts-enforced:
 	 * @msg: the message
 	 *
-	 * Emitted when #SoupHSTSEnforcer has upgraded the protocol
+	 * Emitted when [class@HSTSEnforcer] has upgraded the protocol
 	 * for @msg to HTTPS as a result of matching its domain with
 	 * a HSTS policy.
 	 **/
@@ -702,6 +698,11 @@ soup_message_class_init (SoupMessageClass *message_class)
 			      NULL,
 			      G_TYPE_NONE, 0);
 
+	/**
+	 * SoupMessage:method: (attributes org.gtk.Property.get=soup_message_get_method org.gtk.Property.set=soup_message_set_method)
+	 *
+	 * The message's HTTP method.
+	 **/
 	/* properties */
         properties[PROP_METHOD] =
 		g_param_spec_string ("method",
@@ -710,6 +711,11 @@ soup_message_class_init (SoupMessageClass *message_class)
 				     SOUP_METHOD_GET,
 				     G_PARAM_READWRITE |
 				     G_PARAM_STATIC_STRINGS);
+	/**
+	 * SoupMessage:uri: (attributes org.gtk.Property.get=soup_message_get_uri org.gtk.Property.set=soup_message_set_uri)
+	 *
+	 * The message's Request-URI.
+	 **/
         properties[PROP_URI] =
 		g_param_spec_boxed ("uri",
 				    "URI",
@@ -717,6 +723,11 @@ soup_message_class_init (SoupMessageClass *message_class)
 				    G_TYPE_URI,
 				    G_PARAM_READWRITE |
 				    G_PARAM_STATIC_STRINGS);
+	/**
+	 * SoupMessage:http-version: (attributes org.gtk.Property.get=soup_message_get_http_version)
+	 *
+	 * The HTTP protocol version to use.
+	 **/
         properties[PROP_HTTP_VERSION] =
 		g_param_spec_enum ("http-version",
 				   "HTTP Version",
@@ -725,6 +736,11 @@ soup_message_class_init (SoupMessageClass *message_class)
 				   SOUP_HTTP_1_1,
 				   G_PARAM_READABLE |
 				   G_PARAM_STATIC_STRINGS);
+	/**
+	 * SoupMessage:flags: (attributes org.gtk.Property.get=soup_message_get_flags org.gtk.Property.set=soup_message_set_flags)
+	 *
+	 * Various message options.
+	 **/
         properties[PROP_FLAGS] =
 		g_param_spec_flags ("flags",
 				    "Flags",
@@ -733,6 +749,11 @@ soup_message_class_init (SoupMessageClass *message_class)
 				    0,
 				    G_PARAM_READWRITE |
 				    G_PARAM_STATIC_STRINGS);
+	/**
+	 * SoupMessage:status-code:
+	 *
+	 * The HTTP response status code.
+	 **/
         properties[PROP_STATUS_CODE] =
 		g_param_spec_uint ("status-code",
 				   "Status code",
@@ -740,6 +761,11 @@ soup_message_class_init (SoupMessageClass *message_class)
 				   0, 999, 0,
 				   G_PARAM_READABLE |
 				   G_PARAM_STATIC_STRINGS);
+	/**
+	 * SoupMessage:reason-phrase: (attributes org.gtk.Property.get=soup_message_get_reason_phrase)
+	 *
+	 * The HTTP response reason phrase.
+	 **/
         properties[PROP_REASON_PHRASE] =
 		g_param_spec_string ("reason-phrase",
 				     "Reason phrase",
@@ -748,11 +774,10 @@ soup_message_class_init (SoupMessageClass *message_class)
 				     G_PARAM_READABLE |
 				     G_PARAM_STATIC_STRINGS);
 	/**
-	 * SoupMessage:first-party:
+	 * SoupMessage:first-party: (attributes org.gtk.Property.get=soup_message_get_first_party org.gtk.Property.set=soup_message_set_first_party)
 	 *
-	 * The #GUri loaded in the application when the message was
+	 * The [struct@GLib.Uri] loaded in the application when the message was
 	 * queued.
-	 *
 	 */
         properties[PROP_FIRST_PARTY] =
 		g_param_spec_boxed ("first-party",
@@ -762,10 +787,9 @@ soup_message_class_init (SoupMessageClass *message_class)
 				    G_PARAM_READWRITE |
 				    G_PARAM_STATIC_STRINGS);
 	/**
-	 * SoupMessage:site-for-cookkies:
+	 * SoupMessage:site-for-cookies: (attributes org.gtk.Property.get=soup_message_get_site_for_cookies org.gtk.Property.set=soup_message_set_site_for_cookies)
 	 *
 	 * Site used to compare cookies against. Used for SameSite cookie support.
-	 *
 	 */
         properties[PROP_SITE_FOR_COOKIES] =
 		g_param_spec_boxed ("site-for-cookies",
@@ -774,10 +798,9 @@ soup_message_class_init (SoupMessageClass *message_class)
 				    G_TYPE_URI,
 				    G_PARAM_READWRITE);
 	/**
-	 * SoupMessage:is-top-level-navigation:
+	 * SoupMessage:is-top-level-navigation: (attributes org.gtk.Property.get=soup_message_get_is_top_level_navigation org.gtk.Property.set=soup_message_set_is_top_level_navigation)
 	 *
 	 * Set when the message is navigating between top level domains.
-	 *
 	 */
         properties[PROP_IS_TOP_LEVEL_NAVIGATION] =
 		g_param_spec_boolean ("is-top-level-navigation",
@@ -785,6 +808,11 @@ soup_message_class_init (SoupMessageClass *message_class)
 				     "If the current messsage is navigating between top-levels",
 				     FALSE,
 				     G_PARAM_READWRITE);
+	/**
+	 * SoupMessage:request-headers: (attributes org.gtk.Property.get=soup_message_get_request_headers)
+	 *
+	 * The HTTP request headers.
+	 */
         properties[PROP_REQUEST_HEADERS] =
 		g_param_spec_boxed ("request-headers",
 				    "Request Headers",
@@ -792,6 +820,11 @@ soup_message_class_init (SoupMessageClass *message_class)
 				    SOUP_TYPE_MESSAGE_HEADERS,
 				    G_PARAM_READABLE |
 				    G_PARAM_STATIC_STRINGS);
+	/**
+	 * SoupMessage:response-headers: (attributes org.gtk.Property.get=soup_message_get_response_headers)
+	 *
+	 * The HTTP response headers.
+	 */
         properties[PROP_RESPONSE_HEADERS] =
 		g_param_spec_boxed ("response-headers",
 				    "Response Headers",
@@ -800,10 +833,9 @@ soup_message_class_init (SoupMessageClass *message_class)
 				    G_PARAM_READABLE |
 				    G_PARAM_STATIC_STRINGS);
 	/**
-	 * SoupMessage:tls-peer-certificate:
-	 *
-	 * The peer's #GTlsCertificate associated with the message
+	 * SoupMessage:tls-peer-certificate: (attributes org.gtk.Property.get=soup_message_get_tls_peer_certificate)
 	 *
+	 * The peer's [class@Gio.TlsCertificate] associated with the message.
 	 */
         properties[PROP_TLS_PEER_CERTIFICATE] =
 		g_param_spec_object ("tls-peer-certificate",
@@ -813,10 +845,9 @@ soup_message_class_init (SoupMessageClass *message_class)
 				     G_PARAM_READABLE |
 				     G_PARAM_STATIC_STRINGS);
 	/**
-	 * SoupMessage:tls-peer-certificate-errors:
-	 *
-	 * The verification errors on #SoupMessage:tls-peer-certificate
+	 * SoupMessage:tls-peer-certificate-errors: (attributes org.gtk.Property.get=soup_message_get_tls_peer_certificate_errors)
 	 *
+	 * The verification errors on [property@Message:tls-peer-certificate].
 	 */
         properties[PROP_TLS_PEER_CERTIFICATE_ERRORS] =
 		g_param_spec_flags ("tls-peer-certificate-errors",
@@ -826,7 +857,7 @@ soup_message_class_init (SoupMessageClass *message_class)
 				    G_PARAM_READABLE |
 				    G_PARAM_STATIC_STRINGS);
         /**
-         * SoupMessage:tls-protocol-version:
+         * SoupMessage:tls-protocol-version: (attributes org.gtk.Property.get=soup_message_get_tls_protocol_version)
          *
          * The TLS protocol version negotiated for the message connection.
          */
@@ -840,7 +871,7 @@ soup_message_class_init (SoupMessageClass *message_class)
                                    G_PARAM_STATIC_STRINGS);
 
         /**
-         * SoupMessage:tls-ciphersuite-name:
+         * SoupMessage:tls-ciphersuite-name: (attributes org.gtk.Property.get=soup_message_get_tls_ciphersuite_name)
          *
          * The Name of TLS ciphersuite negotiated for this message connection.
          */
@@ -853,10 +884,10 @@ soup_message_class_init (SoupMessageClass *message_class)
                                      G_PARAM_STATIC_STRINGS);
 
         /**
-         * SoupMessage:remote-address:
-         *
-         * The remote #GSocketAddress of the connection associated with the message
+         * SoupMessage:remote-address: (attributes org.gtk.Property.get=soup_message_get_remote_address)
          *
+         * The remote [class@Gio.SocketAddress] of the connection associated
+         * with the message.
          */
         properties[PROP_REMOTE_ADDRESS] =
                 g_param_spec_object ("remote-address",
@@ -866,11 +897,10 @@ soup_message_class_init (SoupMessageClass *message_class)
                                      G_PARAM_READABLE |
                                      G_PARAM_STATIC_STRINGS);
 	/**
-	 SoupMessage:priority:
+	 SoupMessage:priority: (attributes org.gtk.Property.get=soup_message_get_priority org.gtk.Property.set=soup_message_set_priority)
 	 *
 	 * Sets the priority of the #SoupMessage. See
-	 * soup_message_set_priority() for further details.
-	 *
+	 * [method@Message.set_priority] for further details.
 	 **/
         properties[PROP_PRIORITY] =
 		g_param_spec_enum ("priority",
@@ -882,12 +912,14 @@ soup_message_class_init (SoupMessageClass *message_class)
 				   G_PARAM_STATIC_STRINGS);
 
 	/**
-	 * SoupMessage:is-options-ping:
+	 * SoupMessage:is-options-ping: (attributes org.gtk.Property.get=soup_message_get_is_options_ping org.gtk.Property.set=soup_message_set_is_options_ping)
+	 *
+	 * Whether the message is an OPTIONS ping.
 	 *
 	 * The #SoupMessage is intended to be used to send
          * `OPTIONS *` to a server. When set to %TRUE, the
-         * path of #SoupMessage:uri will be ignored and
-         * #SoupMessage:method set to %SOUP_METHOD_OPTIONS.
+         * path of [property@Message:uri] will be ignored and
+         * [property@Message:method] set to %SOUP_METHOD_OPTIONS.
 	 */
         properties[PROP_IS_OPTIONS_PING] =
 		g_param_spec_boolean ("is-options-ping",
@@ -906,10 +938,10 @@ soup_message_class_init (SoupMessageClass *message_class)
  * @method: the HTTP method for the created request
  * @uri_string: the destination endpoint (as a string)
  * 
- * Creates a new empty #SoupMessage, which will connect to @uri
+ * Creates a new empty #SoupMessage, which will connect to @uri.
  *
  * Returns: (transfer full) (nullable): the new #SoupMessage (or %NULL if @uri
- * could not be parsed).
+ *   could not be parsed).
  */
 SoupMessage *
 soup_message_new (const char *method, const char *uri_string)
@@ -936,9 +968,9 @@ soup_message_new (const char *method, const char *uri_string)
 /**
  * soup_message_new_from_uri:
  * @method: the HTTP method for the created request
- * @uri: the destination endpoint (as a #GUri)
+ * @uri: the destination endpoint
  * 
- * Creates a new empty #SoupMessage, which will connect to @uri
+ * Creates a new empty #SoupMessage, which will connect to @uri.
  *
  * Returns: (transfer full): the new #SoupMessage
  */
@@ -956,10 +988,10 @@ soup_message_new_from_uri (const char *method, GUri *uri)
 
 /**
  * soup_message_new_options_ping:
- * @base_uri: the destination endpoint (as a #GUri)
+ * @base_uri: the destination endpoint
  *
- * Creates a new #SoupMessage to send `OPTIONS *` to a server. The path of @base_uri
- * will be ignored.
+ * Creates a new #SoupMessage to send `OPTIONS *` to a server. The path of
+ * @base_uri will be ignored.
  *
  * Returns: (transfer full): the new #SoupMessage
  */
@@ -985,12 +1017,13 @@ soup_message_new_options_ping (GUri *base_uri)
  * to @uri via @method. If @method is "GET", it will include the form data
  * into @uri's query field, and if @method is "POST" or "PUT", it will be set as
  * request body.
+ *
  * This function takes the ownership of @encoded_form, that will be released
- * with g_free() when no longer in use. See also soup_form_encode(),
- * soup_form_encode_hash() and soup_form_encode_datalist().
+ * with [func@GLib.free] when no longer in use. See also [func@form_encode],
+ * [func@form_encode_hash] and [func@form_encode_datalist].
  *
- * Returns: (transfer full) (nullable): the new #SoupMessage, or %NULL if @uri_string
- *     could not be parsed or @method is not "GET, "POST" or "PUT"
+ * Returns: (transfer full) (nullable): the new #SoupMessage, or %NULL if
+ *   @uri_string could not be parsed or @method is not "GET, "POST" or "PUT"
  */
 SoupMessage *
 soup_message_new_from_encoded_form (const char *method,
@@ -1033,14 +1066,14 @@ soup_message_new_from_encoded_form (const char *method,
 
 /**
  * soup_message_new_from_multipart:
- * @uri_string: the destination endpoint (as a string)
+ * @uri_string: the destination endpoint
  * @multipart: a #SoupMultipart
  *
  * Creates a new #SoupMessage and sets it up to send @multipart to
  * @uri_string via POST.
  *
  * Returns: (transfer full) (nullable): the new #SoupMessage, or %NULL if @uri_string
- *     could not be parsed
+ *   could not be parsed
  */
 SoupMessage *
 soup_message_new_from_multipart (const char    *uri_string,
@@ -1078,6 +1111,7 @@ soup_message_new_from_multipart (const char    *uri_string,
  * @content_length: the byte length of @stream or -1 if unknown
  *
  * Set the request body of a #SoupMessage.
+ *
  * If @content_type is %NULL and @stream is not %NULL the Content-Type header will
  * not be changed if present.
  * The request body needs to be set again in case @msg is restarted
@@ -1123,7 +1157,8 @@ soup_message_set_request_body (SoupMessage  *msg,
  * @content_type: (nullable): MIME Content-Type of the body, or %NULL if unknown
  * @bytes: (nullable): a #GBytes with the request body data
  *
- * Set the request body of a #SoupMessage from #GBytes.
+ * Set the request body of a #SoupMessage from [struct@GLib.Bytes].
+ *
  * If @content_type is %NULL and @bytes is not %NULL the Content-Type header will
  * not be changed if present.
  * The request body needs to be set again in case @msg is restarted
@@ -1258,12 +1293,13 @@ header_handler_metamarshal (GClosure *closure, GValue *return_value,
  * @callback: the header handler
  * @user_data: data to pass to @handler_cb
  *
- * Adds a signal handler to @msg for @signal, as with
- * g_signal_connect(), but the @callback will only be run if @msg's
- * incoming messages headers (that is, the <literal>request_headers</literal>)
- * contain a header named @header.
+ * Adds a signal handler to @msg for @signal.
+ *
+ * Similar to [func@GObject.signal_connect], but the @callback will only be run
+ * if @msg's incoming messages headers (that is, the `request_headers`) contain
+ * a header named @header.
  *
- * Returns: the handler ID from g_signal_connect()
+ * Returns: the handler ID from [func@GObject.signal_connect]
  **/
 guint
 soup_message_add_header_handler (SoupMessage *msg,
@@ -1315,14 +1351,15 @@ status_handler_metamarshal (GClosure *closure, GValue *return_value,
  * @callback: the header handler
  * @user_data: data to pass to @handler_cb
  *
- * Adds a signal handler to @msg for @signal, as with
- * g_signal_connect(), but the @callback will only be run if @msg has
- * the status @status_code.
+ * Adds a signal handler to @msg for @signal.
+ *
+ * Similar to [func@GObject.signal_connect], but the @callback will only be run
+ * if @msg has the status @status_code.
  *
  * @signal must be a signal that will be emitted after @msg's status
  * is set (this means it can't be a "wrote" signal).
  *
- * Returns: the handler ID from g_signal_connect()
+ * Returns: the handler ID from [func@GObject.signal_connect]
  **/
 guint
 soup_message_add_status_code_handler (SoupMessage *msg,
@@ -1773,7 +1810,9 @@ soup_message_has_pending_tls_cert_pass_request (SoupMessage *msg)
  * @msg: a #SoupMessage
  *
  * Cleans up all response data on @msg, so that the request can be sent
- * again and receive a new response. (Eg, as a result of a redirect or
+ * again and receive a new response.
+ *
+ * (Eg, as a result of a redirect or
  * authorization request.)
  **/
 void
@@ -1806,19 +1845,19 @@ soup_message_cleanup_response (SoupMessage *msg)
  * @SOUP_MESSAGE_NEW_CONNECTION: Requests that the message should be
  *   sent on a newly-created connection, not reusing an existing
  *   persistent connection. Note that messages with non-idempotent
- *   #SoupMessage:method<!-- -->s behave this way by default, unless
+ *   [property@Message:method]s behave this way by default, unless
  *   #SOUP_MESSAGE_IDEMPOTENT is set.
  * @SOUP_MESSAGE_IDEMPOTENT: The message is considered idempotent,
- *   regardless its #SoupMessage:method, and allows reuse of existing
+ *   regardless its [property@Message:method], and allows reuse of existing
  *   idle connections, instead of always requiring a new one, unless
  *   #SOUP_MESSAGE_NEW_CONNECTION is set.
- * @SOUP_MESSAGE_DO_NOT_USE_AUTH_CACHE: The #SoupAuthManager should not use
+ * @SOUP_MESSAGE_DO_NOT_USE_AUTH_CACHE: The [class@AuthManager] should not use
  *   the credentials cache for this message, neither to use cached credentials
  *   to automatically authenticate this message nor to cache the credentials
  *   after the message is successfully authenticated. This applies to both server
- *   and proxy authentication. Note that #SoupMessage::authenticate signal will
+ *   and proxy authentication. Note that [signal@Message::authenticate] signal will
  *   be emitted, if you want to disable authentication for a message use
- *   soup_message_disable_feature() passing #SOUP_TYPE_AUTH_MANAGER instead.
+ *   [method@Message.disable_feature] passing #SOUP_TYPE_AUTH_MANAGER instead.
  * @SOUP_MESSAGE_COLLECT_METRICS: Metrics will be collected for this message.
  *
  * Various flags that can be set on a #SoupMessage to alter its
@@ -1826,7 +1865,7 @@ soup_message_cleanup_response (SoupMessage *msg)
  **/
 
 /**
- * soup_message_set_flags:
+ * soup_message_set_flags: (attributes org.gtk.Method.set_property=flags)
  * @msg: a #SoupMessage
  * @flags: a set of #SoupMessageFlags values
  *
@@ -1849,10 +1888,10 @@ soup_message_set_flags (SoupMessage *msg, SoupMessageFlags flags)
 }
 
 /**
- * soup_message_get_flags:
+ * soup_message_get_flags: (attributes org.gtk.Method.get_property=flags)
  * @msg: a #SoupMessage
  *
- * Gets the flags on @msg
+ * Gets the flags on @msg.
  *
  * Returns: the flags
  **/
@@ -1873,7 +1912,7 @@ soup_message_get_flags (SoupMessage *msg)
  * @msg: a #SoupMessage
  * @flags: a set of #SoupMessageFlags values
  *
- * Adds @flags to the set of @msg's flags
+ * Adds @flags to the set of @msg's flags.
  */
 void
 soup_message_add_flags (SoupMessage     *msg,
@@ -1892,7 +1931,7 @@ soup_message_add_flags (SoupMessage     *msg,
  * @msg: a #SoupMessage
  * @flags: a set of #SoupMessageFlags values
  *
- * Queries if @flags are present in the set of @msg's flags
+ * Queries if @flags are present in the set of @msg's flags.
  *
  * Returns: %TRUE if @flags are enabled in @msg
  */
@@ -1913,7 +1952,7 @@ soup_message_query_flags (SoupMessage     *msg,
  * @msg: a #SoupMessage
  * @flags: a set of #SoupMessageFlags values
  *
- * Removes @flags from the set of @msg's flags
+ * Removes @flags from the set of @msg's flags.
  */
 void
 soup_message_remove_flags (SoupMessage     *msg,
@@ -1928,13 +1967,14 @@ soup_message_remove_flags (SoupMessage     *msg,
 }
 
 /**
- * soup_message_set_http_version:
+ * soup_message_set_http_version: (attributes org.gtk.Method.set_property=https-version)
  * @msg: a #SoupMessage
  * @version: the HTTP version
  *
- * Sets the HTTP version on @msg. The default version is
- * %SOUP_HTTP_1_1. Setting it to %SOUP_HTTP_1_0 will prevent certain
- * functionality from being used.
+ * Sets the HTTP version on @msg.
+ *
+ * The default version is %SOUP_HTTP_1_1. Setting it to %SOUP_HTTP_1_0 will
+ * prevent certain functionality from being used.
  **/
 void
 soup_message_set_http_version (SoupMessage *msg, SoupHTTPVersion version)
@@ -1951,11 +1991,13 @@ soup_message_set_http_version (SoupMessage *msg, SoupHTTPVersion version)
 }
 
 /**
- * soup_message_get_http_version:
+ * soup_message_get_http_version: (attributes org.gtk.Method.get_property=http-version)
  * @msg: a #SoupMessage
  *
- * Gets the HTTP version of @msg. This is the minimum of the
- * version from the request and the version from the response.
+ * Gets the HTTP version of @msg.
+ *
+ * This is the minimum of the version from the request and the version from the
+ * response.
  *
  * Returns: the HTTP version
  **/
@@ -1976,8 +2018,9 @@ soup_message_get_http_version (SoupMessage *msg)
  * @msg: a #SoupMessage
  *
  * Determines whether or not @msg's connection can be kept alive for
- * further requests after processing @msg, based on the HTTP version,
- * Connection header, etc.
+ * further requests after processing @msg.
+ *
+ * The result is based on the HTTP version, Connection header, etc.
  *
  * Returns: %TRUE or %FALSE.
  **/
@@ -2025,12 +2068,14 @@ soup_message_is_keepalive (SoupMessage *msg)
 }
 
 /**
- * soup_message_set_uri:
+ * soup_message_set_uri: (attributes org.gtk.Method.set_property=method)
  * @msg: a #SoupMessage
  * @uri: the new #GUri
  *
- * Sets @msg's URI to @uri. If @msg has already been sent and you want
- * to re-send it with the new URI, you need to send it again.
+ * Sets @msg's URI to @uri.
+ *
+ * If @msg has already been sent and you want to re-send it with the new URI,
+ * you need to send it again.
  **/
 void
 soup_message_set_uri (SoupMessage *msg, GUri *uri)
@@ -2061,10 +2106,10 @@ soup_message_set_uri (SoupMessage *msg, GUri *uri)
 }
 
 /**
- * soup_message_get_uri:
+ * soup_message_get_uri: (attributes org.gtk.Method.get_property=method)
  * @msg: a #SoupMessage
  *
- * Gets @msg's URI
+ * Gets @msg's URI.
  *
  * Returns: (transfer none): the URI @msg is targeted for.
  **/
@@ -2085,8 +2130,9 @@ soup_message_get_uri (SoupMessage *msg)
  * @msg: a #SoupMessage
  * @status_code: an HTTP status code
  *
- * Sets @msg's status code to @status_code. If @status_code is a
- * known value, it will also set @msg's reason_phrase.
+ * Sets @msg's status code to @status_code.
+ *
+ * If @status_code is a known value, it will also set @msg's reason_phrase.
  **/
 void
 soup_message_set_status (SoupMessage *msg,
@@ -2118,8 +2164,9 @@ soup_message_set_status (SoupMessage *msg,
  * @msg: a #SoupMessage
  * @feature_type: the #GType of a #SoupSessionFeature
  *
- * This disables the actions of #SoupSessionFeature<!-- -->s with the
- * given @feature_type (or a subclass of that type) on @msg, so that
+ * Disables the actions of [iface@SessionFeature]s with the
+ * given @feature_type (or a subclass of that type) on @msg.
+ *
  * @msg is processed as though the feature(s) hadn't been added to the
  * session. Eg, passing #SOUP_TYPE_CONTENT_SNIFFER for @feature_type
  * will disable Content-Type sniffing on the message.
@@ -2128,7 +2175,6 @@ soup_message_set_status (SoupMessage *msg,
  * a message that has already been queued is undefined. In particular,
  * you cannot call this on a message that is being requeued after a
  * redirect or authentication.
- *
  **/
 void
 soup_message_disable_feature (SoupMessage *msg, GType feature_type)
@@ -2172,12 +2218,12 @@ soup_message_disables_feature (SoupMessage *msg, gpointer feature)
  * @msg: a #SoupMessage
  * @feature_type: the #GType of a #SoupSessionFeature
  *
- * Get whether #SoupSessionFeature<!-- -->s of the given @feature_type
+ * Get whether [iface@SessionFeature]s of the given @feature_type
  * (or a subclass of that type) are disabled on @msg.
- * See soup_message_disable_feature().
  *
- * Returns: %TRUE if feature is disabled, or %FALSE otherwise.
+ * See [method@Message.disable_feature].
  *
+ * Returns: %TRUE if feature is disabled, or %FALSE otherwise.
  */
 gboolean
 soup_message_is_feature_disabled (SoupMessage *msg, GType feature_type)
@@ -2210,13 +2256,12 @@ soup_message_get_disabled_features (SoupMessage *msg)
 }
 
 /**
- * soup_message_get_first_party:
+ * soup_message_get_first_party: (attributes org.gtk.Method.get_property=first-party)
  * @msg: a #SoupMessage
  *
- * Gets @msg's first-party #GUri
+ * Gets @msg's first-party [struct@GLib.Uri].
  * 
  * Returns: (transfer none): the @msg's first party #GUri
- * 
  **/
 GUri *
 soup_message_get_first_party (SoupMessage *msg)
@@ -2230,14 +2275,14 @@ soup_message_get_first_party (SoupMessage *msg)
 }
 
 /**
- * soup_message_set_first_party:
+ * soup_message_set_first_party: (attributes org.gtk.Method.set_property=first-party)
  * @msg: a #SoupMessage
  * @first_party: the #GUri for the @msg's first party
  * 
- * Sets @first_party as the main document #GUri for @msg. For
- * details of when and how this is used refer to the documentation for
- * #SoupCookieJarAcceptPolicy.
+ * Sets @first_party as the main document #GUri for @msg.
  *
+ * For details of when and how this is used refer to the documentation for
+ * [enum@CookieJarAcceptPolicy].
  **/
 void
 soup_message_set_first_party (SoupMessage *msg,
@@ -2268,13 +2313,12 @@ soup_message_set_first_party (SoupMessage *msg,
 }
 
 /**
- * soup_message_get_site_for_cookies:
+ * soup_message_get_site_for_cookies: (attributes org.gtk.Method.get_property=site-for-cookies)
  * @msg: a #SoupMessage
  *
- * Gets @msg's site for cookies #GUri
+ * Gets @msg's site for cookies #GUri.
  *
  * Returns: (transfer none): the @msg's site for cookies #GUri
- *
  **/
 GUri *
 soup_message_get_site_for_cookies (SoupMessage *msg)
@@ -2288,19 +2332,19 @@ soup_message_get_site_for_cookies (SoupMessage *msg)
 }
 
 /**
- * soup_message_set_site_for_cookies:
+ * soup_message_set_site_for_cookies: (attributes org.gtk.Method.set_property=site-for-cookies)
  * @msg: a #SoupMessage
  * @site_for_cookies: (nullable): the #GUri for the @msg's site for cookies
  *
  * Sets @site_for_cookies as the policy URL for same-site cookies for @msg.
  *
- * It is either the URL of the top-level document or %NULL depending on whether the registrable
- * domain of this document's URL matches the registrable domain of its parent's/opener's
- * URL. For the top-level document it is set to the document's URL.
+ * It is either the URL of the top-level document or %NULL depending on whether
+ * the registrable domain of this document's URL matches the registrable domain
+ * of its parent's/opener's URL. For the top-level document it is set to the
+ * document's URL.
  *
  * See the [same-site spec](https://tools.ietf.org/html/draft-ietf-httpbis-cookie-same-site-00)
  * for more information.
- *
  **/
 void
 soup_message_set_site_for_cookies (SoupMessage *msg,
@@ -2332,13 +2376,14 @@ soup_message_set_site_for_cookies (SoupMessage *msg,
 }
 
 /**
- * soup_message_set_is_top_level_navigation:
+ * soup_message_set_is_top_level_navigation: (attributes org.gtk.Method.set_property=is-top-level-navigation)
  * @msg: a #SoupMessage
  * @is_top_level_navigation: if %TRUE indicate the current request is a top-level navigation
  *
+ * Sets whether the current request is a top-level navitation.
+ *
  * See the [same-site spec](https://tools.ietf.org/html/draft-ietf-httpbis-cookie-same-site-00)
  * for more information.
- *
  **/
 void
 soup_message_set_is_top_level_navigation (SoupMessage *msg,
@@ -2358,12 +2403,14 @@ soup_message_set_is_top_level_navigation (SoupMessage *msg,
 }
 
 /**
- * soup_message_get_is_top_level_navigation:
+ * soup_message_get_is_top_level_navigation: (attributes org.gtk.Method.get_property=is-top-level-navigation)
  * @msg: a #SoupMessage
  *
  * Returns if this message is set as a top level navigation.
+ *
  * Used for same-site policy checks.
  *
+ * Returns: Whether the current request is a top-level navitation
  **/
 gboolean
 soup_message_get_is_top_level_navigation (SoupMessage *msg)
@@ -2380,12 +2427,13 @@ soup_message_get_is_top_level_navigation (SoupMessage *msg)
  * soup_message_get_tls_peer_certificate:
  * @msg: a #SoupMessage
  *
- * Gets the peer's #GTlsCertificate associated with @msg's connection.
+ * Gets the peer's [class@Gio.TlsCertificate] associated with @msg's connection.
+ *
  * Note that this is not set yet during the emission of
- * SoupMessage::accept-certificate signal.
+ * [signal@Message::accept-certificate] signal.
  *
  * Returns: (transfer none) (nullable): @msg's TLS peer certificate,
- *    or %NULL if @msg's connection is not SSL.
+ *   or %NULL if @msg's connection is not SSL.
  */
 GTlsCertificate *
 soup_message_get_tls_peer_certificate (SoupMessage *msg)
@@ -2405,7 +2453,7 @@ soup_message_get_tls_peer_certificate (SoupMessage *msg)
  *
  * Gets the errors associated with validating @msg's TLS peer certificate.
  * Note that this is not set yet during the emission of
- * SoupMessage::accept-certificate signal.
+ * [signal@Message::accept-certificate] signal.
  *
  * Returns: a #GTlsCertificateFlags with @msg's TLS peer certificate errors.
  */
@@ -2426,6 +2474,7 @@ soup_message_get_tls_peer_certificate_errors (SoupMessage *msg)
  * @msg: a #SoupMessage
  *
  * Gets the TLS protocol version negotiated for @msg's connection.
+ *
  * If the message connection is not SSL, %G_TLS_PROTOCOL_VERSION_UNKNOWN is returned.
  *
  * Returns: a #GTlsProtocolVersion
@@ -2449,7 +2498,7 @@ soup_message_get_tls_protocol_version (SoupMessage *msg)
  * Gets the name of the TLS ciphersuite negotiated for @msg's connection.
  *
  * Returns: (transfer none): the name of the TLS ciphersuite,
- *    or %NULL if @msg's connection is not SSL.
+ *   or %NULL if @msg's connection is not SSL.
  */
 const char *
 soup_message_get_tls_ciphersuite_name (SoupMessage *msg)
@@ -2470,11 +2519,12 @@ soup_message_get_tls_ciphersuite_name (SoupMessage *msg)
  *
  * Sets the @certificate to be used by @msg's connection when a
  * client certificate is requested during the TLS handshake.
- * You can call this as a response to #SoupMessage::request-certificate
+ *
+ * You can call this as a response to [signal@Message::request-certificate]
  * signal, or before the connection is started. If @certificate is %NULL
  * the handshake will continue without providing a GTlsCertificate.
- * Note that the #GTlsCertificate set by this function will be ignored if
- * #SoupSession::tls-interaction is not %NULL.
+ * Note that the [class@Gio.TlsCertificate] set by this function will be ignored if
+ * [property@Session:tls-interaction] is not %NULL.
  */
 void
 soup_message_set_tls_client_certificate (SoupMessage     *msg,
@@ -2513,8 +2563,9 @@ soup_message_set_tls_client_certificate (SoupMessage     *msg,
  *
  * Completes a certificate password request.
  *
- * You must call this as a response to #SoupMessage::request-certificate-password
- * signal, to notify @msg that the #GTlsPassword has already been updated.
+ * You must call this as a response to
+ * [signal@Message::request-certificate-password] signal, to notify @msg that
+ * the [class@Gio.TlsPassword] has already been updated.
  */
 void
 soup_message_tls_client_certificate_password_request_complete (SoupMessage *msg)
@@ -2549,9 +2600,8 @@ soup_message_tls_client_certificate_password_request_complete (SoupMessage *msg)
  *   for very urgent #SoupMessage as they will be the first ones to be
  *   attended.
  *
- * Priorities that can be set on a #SoupMessage to instruct the
- * message queue to process it before any other message with lower
- * priority.
+ * Priorities that can be set on a [class@Message] to instruct the message queue
+ * to process it before any other message with lower priority.
  **/
 
 /**
@@ -2559,9 +2609,10 @@ soup_message_tls_client_certificate_password_request_complete (SoupMessage *msg)
  * @msg: a #SoupMessage
  * @priority: the #SoupMessagePriority
  *
- * Sets the priority of a message. Note that this won't have any
- * effect unless used before the message is added to the session's
- * message processing queue.
+ * Sets the priority of a message.
+ *
+ * Note that this won't have any effect unless used before the message is added
+ * to the session's message processing queue.
  *
  * The message will be placed just before any other previously added
  * message with lower priority (messages with the same priority are
@@ -2570,7 +2621,6 @@ soup_message_tls_client_certificate_password_request_complete (SoupMessage *msg)
  * Setting priorities does not currently work with synchronous messages
  * because in the synchronous/blocking case, priority ends up being determined
  * semi-randomly by thread scheduling.
- *
  */
 void
 soup_message_set_priority (SoupMessage        *msg,
@@ -2592,11 +2642,11 @@ soup_message_set_priority (SoupMessage        *msg,
  * soup_message_get_priority:
  * @msg: a #SoupMessage
  *
- * Retrieves the #SoupMessagePriority. If not set this value defaults
- * to #SOUP_MESSAGE_PRIORITY_NORMAL.
+ * Retrieves the [enum@MessagePriority].
  *
- * Returns: the priority of the message.
+ * If not set this value defaults to #SOUP_MESSAGE_PRIORITY_NORMAL.
  *
+ * Returns: the priority of the message.
  */
 SoupMessagePriority
 soup_message_get_priority (SoupMessage *msg)
@@ -2810,7 +2860,7 @@ soup_message_get_request_body_stream (SoupMessage *msg)
 }
 
 /**
- * soup_message_get_method:
+ * soup_message_get_method: (attributes org.gtk.Method.get_property=method)
  * @msg: The #SoupMessage
  *
  * Returns the method of this message.
@@ -2846,7 +2896,7 @@ soup_message_get_status (SoupMessage *msg)
 }
 
 /**
- * soup_message_get_reason_phrase:
+ * soup_message_get_reason_phrase: (attributes org.gtk.Method.get_property=reason-phrase)
  * @msg: The #SoupMessage
  *
  * Returns the reason phrase for the status of this message.
@@ -2864,7 +2914,7 @@ soup_message_get_reason_phrase (SoupMessage *msg)
 }
 
 /**
- * soup_message_get_request_headers:
+ * soup_message_get_request_headers: (attributes org.gtk.Method.get_property=request-headers)
  * @msg: The #SoupMessage
  *
  * Returns the headers sent with the request.
@@ -2882,7 +2932,7 @@ soup_message_get_request_headers (SoupMessage  *msg)
 }
 
 /**
- * soup_message_get_response_headers:
+ * soup_message_get_response_headers: (attributes org.gtk.Method.get_property=response-headers)
  * @msg: The #SoupMessage
  *
  * Returns the headers recieved with the response.
@@ -2899,6 +2949,13 @@ soup_message_get_response_headers (SoupMessage  *msg)
         return priv->response_headers; 
 }
 
+/**
+ * soup_message_set_reason_phrase: (attributes org.gtk.Method.set_property=reason-phrase)
+ * @msg: The #SoupMessage
+ * @reason_phrase: The reason phrase
+ *
+ * Sets the reason phrase for the status of this message.
+ */
 void
 soup_message_set_reason_phrase (SoupMessage *msg, const char *reason_phrase)
 {
@@ -2913,7 +2970,7 @@ soup_message_set_reason_phrase (SoupMessage *msg, const char *reason_phrase)
 }
 
 /**
- * soup_message_set_method:
+ * soup_message_set_method: (attributes org.gtk.Method.set_property=method)
  * @msg: a #SoupMessage
  * @method: the value to set
  *
@@ -2959,8 +3016,9 @@ soup_message_get_is_options_ping (SoupMessage *msg)
  * @is_options_ping: the value to set
  *
  * Set whether @msg is intended to be used to send `OPTIONS *` to a server.
- * When set to %TRUE, the path of #SoupMessage:uri will be ignored and
- * #SoupMessage:method set to %SOUP_METHOD_OPTIONS.
+ *
+ * When set to %TRUE, the path of [property@Message:uri] will be ignored and
+ * [property@Message:method] set to %SOUP_METHOD_OPTIONS.
  */
 void
 soup_message_set_is_options_ping (SoupMessage *msg,
@@ -2985,6 +3043,7 @@ soup_message_set_is_options_ping (SoupMessage *msg,
  * @msg: The #SoupMessage
  *
  * Returns the unique idenfier for the last connection used.
+ *
  * This may be 0 if it was a cached resource or it has not gotten
  * a connection yet.
  *
@@ -3004,12 +3063,14 @@ soup_message_get_connection_id (SoupMessage *msg)
  * soup_message_get_remote_address:
  * @msg: The #SoupMessage
  *
- * Get the remote #GSocketAddress of the connection associated with the message.
- * The returned address can be %NULL if the connection hasn't been established yet,
- * or the resource was loaded from the disk cache.
- * In case of proxy connections, the remote address returned is a #GProxyAddress.
- * If #SoupSession::remote-connetable is set the returned address id for the connection
- * ot the session's remote connectable.
+ * Get the remote [class@Gio.SocketAddress] of the connection associated with
+ * the message.
+ *
+ * The returned address can be %NULL if the connection hasn't been established
+ * yet, or the resource was loaded from the disk cache. In case of proxy
+ * connections, the remote address returned is a [class@Gio.ProxyAddress]. If
+ * [property@Session:remote-connectable] is set the returned address id for the
+ * connection ot the session's remote connectable.
  *
  * Returns: (transfer none) (nullable): a #GSocketAddress or %NULL if the connection
  *     hasn't been established
@@ -3029,10 +3090,12 @@ soup_message_get_remote_address (SoupMessage *msg)
  * soup_message_get_metrics:
  * @msg: The #SoupMessage
  *
- * Get the #SoupMessageMetrics of @msg. If the flag %SOUP_MESSAGE_COLLECT_METRICS is not
- * enabled for @msg this will return %NULL.
+ * Get the [struct@MessageMetrics] of @msg.
+ *
+ * If the flag %SOUP_MESSAGE_COLLECT_METRICS is not enabled for @msg this will
+ * return %NULL.
  *
- * Returns: (transfer none) (nullable): a #SoupMessageMetrics, or %NULL
+ * Returns: (transfer none) (nullable): a #SoupMessageMetrics
  */
 SoupMessageMetrics *
 soup_message_get_metrics (SoupMessage *msg)
diff --git a/libsoup/soup-misc.c b/libsoup/soup-misc.c
index 5ef87994..7f7fa290 100644
--- a/libsoup/soup-misc.c
+++ b/libsoup/soup-misc.c
@@ -92,16 +92,16 @@ soup_add_completion (GMainContext *async_context,
 /**
  * soup_add_timeout: (skip)
  * @async_context: (nullable): the #GMainContext to dispatch the I/O
- * watch in, or %NULL for the default context
+ *   watch in, or %NULL for the default context
  * @interval: the timeout interval, in milliseconds
  * @function: the callback to invoke at timeout time
  * @data: user data to pass to @function
  *
- * Adds a timeout as with g_timeout_add(), but using the given
+ * Adds a timeout as with [func@GLib.timeout_add], but using the given
  * @async_context.
  *
  * Returns: (transfer full): a #GSource, which can be removed from @async_context
- * with g_source_destroy().
+ *   with [method@GLib.Source.destroy].
  **/
 GSource *
 soup_add_timeout (GMainContext *async_context,
diff --git a/libsoup/soup-multipart-input-stream.c b/libsoup/soup-multipart-input-stream.c
index f3c33849..c5d4af7e 100644
--- a/libsoup/soup-multipart-input-stream.c
+++ b/libsoup/soup-multipart-input-stream.c
@@ -21,27 +21,21 @@
 #define RESPONSE_BLOCK_SIZE 8192
 
 /**
- * SECTION:soup-multipart-input-stream
- * @short_description: Multipart input handling stream
+ * SoupMultipartInputStream:
+ *
+ * Handles streams of multipart messages.
  *
  * This adds support for the multipart responses. For handling the
- * multiple parts the user needs to wrap the #GInputStream obtained by
- * sending the request with a #SoupMultipartInputStream and use
- * soup_multipart_input_stream_next_part() before reading. Responses
+ * multiple parts the user needs to wrap the [class@Gio.InputStream] obtained by
+ * sending the request with a [class@MultipartInputStream] and use
+ * [method@MultipartInputStream.next_part] before reading. Responses
  * which are not wrapped will be treated like non-multipart responses.
  *
- * Note that although #SoupMultipartInputStream is a #GInputStream,
+ * Note that although #SoupMultipartInputStream is a [class@Gio.InputStream],
  * you should not read directly from it, and the results are undefined
  * if you do.
- *
  **/
 
-/**
- * SoupMultipartInputStream:
- *
- * Class for handling streams of multipart messages.
- */
-
 enum {
 	PROP_0,
 
@@ -310,6 +304,11 @@ soup_multipart_input_stream_class_init (SoupMultipartInputStreamClass *multipart
 
 	input_stream_class->read_fn = soup_multipart_input_stream_read;
 
+        /**
+         * SoupMultipartInputStream:message:
+         *
+         * The [class@Message].
+         */
         properties[PROP_MESSAGE] =
 		g_param_spec_object ("message",
 				     "Message",
@@ -433,13 +432,13 @@ soup_multipart_input_stream_read_headers (SoupMultipartInputStream  *multipart,
  * @base_stream: the #GInputStream returned by sending the request.
  *
  * Creates a new #SoupMultipartInputStream that wraps the
- * #GInputStream obtained by sending the #SoupMessage. Reads should
- * not be done directly through this object, use the input streams
- * returned by soup_multipart_input_stream_next_part() or its async
+ * [class@Gio.InputStream] obtained by sending the [class@Message].
+ *
+ * Reads should not be done directly through this object, use the input streams
+ * returned by [method@MultipartInputStream.next_part] or its async
  * counterpart instead.
  *
  * Returns: a new #SoupMultipartInputStream
- *
  **/
 SoupMultipartInputStream *
 soup_multipart_input_stream_new (SoupMessage  *msg,
@@ -457,21 +456,20 @@ soup_multipart_input_stream_new (SoupMessage  *msg,
  * @cancellable: a #GCancellable
  * @error: a #GError
  *
- * Obtains an input stream for the next part. When dealing with a
- * multipart response the input stream needs to be wrapped in a
- * #SoupMultipartInputStream and this function or its async
- * counterpart need to be called to obtain the first part for
- * reading.
+ * Obtains an input stream for the next part.
+ *
+ * When dealing with a multipart response the input stream needs to be wrapped
+ * in a #SoupMultipartInputStream and this function or its async counterpart
+ * need to be called to obtain the first part for reading.
  *
  * After calling this function,
- * soup_multipart_input_stream_get_headers() can be used to obtain the
+ * [method@MultipartInputStream.get_headers] can be used to obtain the
  * headers for the first part. A read of 0 bytes indicates the end of
  * the part; a new call to this function should be done at that point,
  * to obtain the next part.
  *
  * Returns: (nullable) (transfer full): a new #GInputStream, or
- * %NULL if there are no more parts
- *
+ *   %NULL if there are no more parts
  */
 GInputStream *
 soup_multipart_input_stream_next_part (SoupMultipartInputStream  *multipart,
@@ -523,10 +521,9 @@ soup_multipart_input_stream_next_part_thread (GTask        *task,
  * @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.
+ * Obtains a [class@Gio.InputStream] for the next request.
  *
+ * See [method@MultipartInputStream.next_part] for details on the workflow.
  */
 void
 soup_multipart_input_stream_next_part_async (SoupMultipartInputStream *multipart,
@@ -563,9 +560,8 @@ soup_multipart_input_stream_next_part_async (SoupMultipartInputStream *multipart
  * Finishes an asynchronous request for the next part.
  *
  * Returns: (nullable) (transfer full): a newly created
- * #GInputStream for reading the next part or %NULL if there are no
- * more parts.
- *
+ *   [class@Gio.InputStream] for reading the next part or %NULL if there are no
+ *   more parts.
  */
 GInputStream *
 soup_multipart_input_stream_next_part_finish (SoupMultipartInputStream	*multipart,
@@ -581,20 +577,19 @@ soup_multipart_input_stream_next_part_finish (SoupMultipartInputStream	*multipar
  * soup_multipart_input_stream_get_headers:
  * @multipart: a #SoupMultipartInputStream.
  *
- * Obtains the headers for the part currently being processed. Note
- * that the #SoupMessageHeaders that are returned are owned by the
- * #SoupMultipartInputStream and will be replaced when a call is made
- * to soup_multipart_input_stream_next_part() or its async
- * counterpart, so if keeping the headers is required, a copy must be
- * made.
+ * Obtains the headers for the part currently being processed.
+ *
+ * Note that the [struct@MessageHeaders] that are returned are owned by the
+ * #SoupMultipartInputStream and will be replaced when a call is made to
+ * [method@MultipartInputStream.next_part] or its async counterpart, so if
+ * keeping the headers is required, a copy must be made.
  *
- * Note that if a part had no headers at all an empty #SoupMessageHeaders
+ * Note that if a part had no headers at all an empty [struct@MessageHeaders]
  * will be returned.
  *
  * Returns: (nullable) (transfer none): a #SoupMessageHeaders
- * containing the headers for the part currently being processed or
- * %NULL if the headers failed to parse.
- *
+ *   containing the headers for the part currently being processed or
+ *   %NULL if the headers failed to parse.
  */
 SoupMessageHeaders *
 soup_multipart_input_stream_get_headers (SoupMultipartInputStream *multipart)
diff --git a/libsoup/soup-multipart.c b/libsoup/soup-multipart.c
index 0bc13fa0..0324b54e 100644
--- a/libsoup/soup-multipart.c
+++ b/libsoup/soup-multipart.c
@@ -17,20 +17,13 @@
 #include "soup.h"
 
 /**
- * SECTION:soup-multipart
- * @short_description: multipart HTTP message bodies
- * @see_also: #SoupMessageBody, #SoupMessageHeaders
- *
- * Functions to use multi-part HTTP messages.
- **/
-
-/**
  * SoupMultipart:
  *
  * Represents a multipart HTTP message body, parsed according to the
- * syntax of RFC 2046. Of particular interest to HTTP are
- * <literal>multipart/byte-ranges</literal> and
- * <literal>multipart/form-data</literal>.
+ * syntax of RFC 2046.
+ *
+ * Of particular interest to HTTP are `multipart/byte-ranges` and
+ * `multipart/form-data`,
  *
  * Although the headers of a #SoupMultipart body part will contain the
  * full headers from that body part, libsoup does not interpret them
@@ -81,12 +74,13 @@ generate_boundary (void)
  * @mime_type: the MIME type of the multipart to create.
  *
  * Creates a new empty #SoupMultipart with a randomly-generated
- * boundary string. Note that @mime_type must be the full MIME type,
- * including "multipart/".
+ * boundary string.
+ *
+ * Note that @mime_type must be the full MIME type, including "multipart/".
+ *
+ * See also: [ctor@Message.new_from_multipart].
  * 
  * Returns: a new empty #SoupMultipart of the given @mime_type
- *
- * See also: soup_message_new_from_multipart()
  **/
 SoupMultipart *
 soup_multipart_new (const char *mime_type)
@@ -129,8 +123,7 @@ find_boundary (const char *start, const char *end,
  * Parses @headers and @body to form a new #SoupMultipart
  *
  * Returns: (nullable): a new #SoupMultipart (or %NULL if the
- * message couldn't be parsed or wasn't multipart).
- *
+ *   message couldn't be parsed or wasn't multipart).
  **/
 SoupMultipart *
 soup_multipart_new_from_message (SoupMessageHeaders *headers,
@@ -224,10 +217,9 @@ soup_multipart_new_from_message (SoupMessageHeaders *headers,
  * soup_multipart_get_length:
  * @multipart: a #SoupMultipart
  *
- * Gets the number of body parts in @multipart
+ * Gets the number of body parts in @multipart.
  *
  * Returns: the number of body parts in @multipart
- *
  **/
 int
 soup_multipart_get_length (SoupMultipart *multipart)
@@ -240,15 +232,14 @@ soup_multipart_get_length (SoupMultipart *multipart)
  * @multipart: a #SoupMultipart
  * @part: the part number to get (counting from 0)
  * @headers: (out) (transfer none): return location for the MIME part
- * headers
+ *   headers
  * @body: (out) (transfer none): return location for the MIME part
- * body
+ *   body
  *
  * Gets the indicated body part from @multipart.
  *
  * Returns: %TRUE on success, %FALSE if @part is out of range (in
- * which case @headers and @body won't be set)
- *
+ *   which case @headers and @body won't be set)
  **/
 gboolean
 soup_multipart_get_part (SoupMultipart *multipart, int part,
@@ -268,10 +259,10 @@ soup_multipart_get_part (SoupMultipart *multipart, int part,
  * @body: the MIME part body
  *
  * Adds a new MIME part to @multipart with the given headers and body.
+ *
  * (The multipart will make its own copies of @headers and @body, so
  * you should free your copies if you are not using them for anything
  * else.)
- *
  **/
 void
 soup_multipart_append_part (SoupMultipart      *multipart,
@@ -319,11 +310,10 @@ soup_multipart_append_part (SoupMultipart      *multipart,
  * @control_name: the name of the control associated with @data
  * @data: the body data
  *
- * Adds a new MIME part containing @data to @multipart, using
- * "Content-Disposition: form-data", as per the HTML forms
- * specification.
+ * Adds a new MIME part containing @data to @multipart.
  *
- **/ 
+ * Uses "Content-Disposition: form-data", as per the HTML forms specification.
+ **/
 void
 soup_multipart_append_form_string (SoupMultipart *multipart,
 				   const char *control_name, const char *data)
@@ -344,11 +334,10 @@ soup_multipart_append_form_string (SoupMultipart *multipart,
  * @content_type: the MIME type of the file, or %NULL if not known
  * @body: the file data
  *
- * Adds a new MIME part containing @body to @multipart, using
- * "Content-Disposition: form-data", as per the HTML forms
- * specification.
+ * Adds a new MIME part containing @body to @multipart
  *
- **/ 
+ * Uses "Content-Disposition: form-data", as per the HTML forms specification.
+ **/
 void
 soup_multipart_append_form_file (SoupMultipart *multipart,
 				 const char *control_name, const char *filename,
@@ -384,7 +373,6 @@ soup_multipart_append_form_file (SoupMultipart *multipart,
  * @dest_body: (out): the body of the HTTP message to serialize @multipart to
  *
  * Serializes @multipart to @dest_headers and @dest_body.
- *
  **/
 void
 soup_multipart_to_message (SoupMultipart      *multipart,
@@ -442,8 +430,7 @@ soup_multipart_to_message (SoupMultipart      *multipart,
  * soup_multipart_free:
  * @multipart: a #SoupMultipart
  *
- * Frees @multipart
- *
+ * Frees @multipart.
  **/
 void
 soup_multipart_free (SoupMultipart *multipart)
diff --git a/libsoup/soup-session-feature.c b/libsoup/soup-session-feature.c
index a0a694a1..5545d984 100644
--- a/libsoup/soup-session-feature.c
+++ b/libsoup/soup-session-feature.c
@@ -14,24 +14,17 @@
 #include "soup-message-private.h"
 
 /**
- * SECTION:soup-session-feature
- * @short_description: Interface for miscellaneous session features
+ * SoupSessionFeature:
+ *
+ * Interface for miscellaneous [class@Session] features.
  *
  * #SoupSessionFeature is the interface used by classes that extend
- * the functionality of a #SoupSession. Some features like HTTP
+ * the functionality of a [class@Session]. Some features like HTTP
  * authentication handling are implemented internally via
- * #SoupSessionFeature<!-- -->s. Other features can be added to the session
- * by the application. (Eg, #SoupLogger, #SoupCookieJar.)
- *
- * See soup_session_add_feature(), etc, to add a feature to a session.
- **/
-
-/**
- * SoupSessionFeature:
- *
- * An object that implement some sort of optional feature for
- * #SoupSession.
+ * `SoupSessionFeature`s. Other features can be added to the session
+ * by the application. (Eg, [class@Logger], [class@CookieJar].)
  *
+ * See [method@Session.add_feature], etc, to add a feature to a session.
  **/
 
 /**
@@ -39,14 +32,13 @@
  * @parent: The parent interface.
  * @attach: Perform setup when a feature is added to a session
  * @detach: Perform cleanup when a feature is removed from a session
- * @request_queued: Proxies the session's #SoupSession::request_queued signal
- * @request_unqueued: Proxies the session's #SoupSession::request_unqueued signal
+ * @request_queued: Proxies the session's [signal@Session::request_queued] signal
+ * @request_unqueued: Proxies the session's [signal@Session::request_unqueued] signal
  * @add_feature: adds a sub-feature to the main feature
  * @remove_feature: removes a sub-feature from the main feature
  * @has_feature: tests if the feature includes a sub-feature
  *
- * The interface implemented by #SoupSessionFeature<!-- -->s.
- *
+ * The interface implemented by [iface@SessionFeature]s.
  **/
 
 G_DEFINE_INTERFACE (SoupSessionFeature, soup_session_feature, G_TYPE_OBJECT)
@@ -124,12 +116,12 @@ soup_session_feature_request_unqueued (SoupSessionFeature *feature,
  * @type: the #GType of a "sub-feature"
  *
  * Adds a "sub-feature" of type @type to the base feature @feature.
+ *
  * This is used for features that can be extended with multiple
  * different types. Eg, the authentication manager can be extended
- * with subtypes of #SoupAuth.
+ * with subtypes of [class@Auth].
  *
  * Returns: %TRUE if @feature accepted @type as a subfeature.
- *
  */
 gboolean
 soup_session_feature_add_feature (SoupSessionFeature *feature,
@@ -150,10 +142,11 @@ soup_session_feature_add_feature (SoupSessionFeature *feature,
  * @type: the #GType of a "sub-feature"
  *
  * Removes the "sub-feature" of type @type from the base feature
- * @feature. See soup_session_feature_add_feature().
+ * @feature.
  *
- * Returns: %TRUE if @type was removed from @feature
+ * See [method@SessionFeature.add_feature].
  *
+ * Returns: %TRUE if @type was removed from @feature
  */
 gboolean
 soup_session_feature_remove_feature (SoupSessionFeature *feature,
@@ -173,11 +166,11 @@ soup_session_feature_remove_feature (SoupSessionFeature *feature,
  * @feature: the "base" feature
  * @type: the #GType of a "sub-feature"
  *
- * Tests if @feature has a "sub-feature" of type @type. See
- * soup_session_feature_add_feature().
+ * Tests if @feature has a "sub-feature" of type @type.
  *
- * Returns: %TRUE if @feature has a subfeature of type @type
+ * See [method@SessionFeature.add_feature].
  *
+ * Returns: %TRUE if @feature has a subfeature of type @type
  */
 gboolean
 soup_session_feature_has_feature (SoupSessionFeature *feature,
diff --git a/libsoup/soup-session.c b/libsoup/soup-session.c
index 319174f3..9dc3d111 100644
--- a/libsoup/soup-session.c
+++ b/libsoup/soup-session.c
@@ -31,9 +31,11 @@
 
 #define HOST_KEEP_ALIVE 5 * 60 * 1000 /* 5 min in msecs */
 
+
 /**
- * SECTION:soup-session
- * @short_description: Soup session state object
+ * SoupSession:
+ *
+ * Soup session state object.
  *
  * #SoupSession is the object that controls client-side HTTP. A
  * #SoupSession encapsulates all of the state that libsoup is keeping
@@ -45,36 +47,30 @@
  * reason you might need multiple sessions is if you need to have
  * multiple independent authentication contexts. (Eg, you are
  * connecting to a server and authenticating as two different users at
- * different times; the easiest way to ensure that each #SoupMessage
+ * different times; the easiest way to ensure that each [class@Message]
  * is sent with the authentication information you intended is to use
  * one session for the first user, and a second session for the other
  * user.)
  *
  * Additional #SoupSession functionality is provided by
- * #SoupSessionFeature objects, which can be added to a session with
- * soup_session_add_feature() or soup_session_add_feature_by_type()
- * For example, #SoupLogger provides support for
- * logging HTTP traffic, #SoupContentDecoder provides support for
- * compressed response handling, and #SoupContentSniffer provides
+ * [iface@SessionFeature] objects, which can be added to a session with
+ * [method@Session.add_feature] or [method@Session.add_feature_by_type]
+ * For example, [class@Logger] provides support for
+ * logging HTTP traffic, [class@ContentDecoder] provides support for
+ * compressed response handling, and [class@ContentSniffer] provides
  * support for HTML5-style response body content sniffing.
- * Additionally, subtypes of #SoupAuth can be added
+ * Additionally, subtypes of [class@Auth] can be added
  * as features, to add support for additional authentication types.
  *
- * All #SoupSessions are created with a #SoupAuthManager, and support
+ * All `SoupSession`s are created with a [class@AuthManager], and support
  * for %SOUP_TYPE_AUTH_BASIC and %SOUP_TYPE_AUTH_DIGEST. Additionally,
  * sessions using the plain #SoupSession class (rather than one of its deprecated
- * subtypes) have a #SoupContentDecoder by default.
+ * subtypes) have a [class@ContentDecoder] by default.
  *
  * Note that all async methods will invoke their callbacks on the thread-default
  * context at the time of the function call.
  **/
 
-/**
- * SoupSession:
- *
- * Class managing options and state for #SoupMessage<!-- -->s.
- */
-
 typedef struct {
 	GUri            *uri;
 	GNetworkAddress *addr;
@@ -184,12 +180,6 @@ enum {
 static GParamSpec *properties[LAST_PROPERTY] = { NULL, };
 
 /**
- * SOUP_SESSION_ERROR:
- *
- * A #GError domain for #SoupSession<!-- -->-related errors. Used with
- * #SoupSessionError.
- */
-/**
  * SoupSessionError:
  * @SOUP_SESSION_ERROR_PARSING: the server's response could not
  *   be parsed
@@ -469,7 +459,6 @@ soup_session_get_property (GObject *object, guint prop_id,
  * Creates a #SoupSession with the default options.
  *
  * Returns: the new session.
- *
  */
 SoupSession *
 soup_session_new (void)
@@ -485,7 +474,6 @@ soup_session_new (void)
  * Creates a #SoupSession with the specified options.
  *
  * Returns: the new session.
- *
  */
 SoupSession *
 soup_session_new_with_options (const char *optname1,
@@ -503,12 +491,13 @@ soup_session_new_with_options (const char *optname1,
 }
 
 /**
- * soup_session_get_local_address:
+ * soup_session_get_local_address: (attributes org.gtk.Method.get_property=local-address)
  * @session: a #SoupSession
  *
- * Get the #GInetSocketAddress to use for the client side of connections in @session.
+ * Get the [class@Gio.InetSocketAddress] to use for the client side of
+ * connections in @session.
  *
- * Returns: (transfer none) (nullable): a #GInetSocketAddress or %NULL
+ * Returns: (transfer none) (nullable): a #GInetSocketAddress
  */
 GInetSocketAddress *
 soup_session_get_local_address (SoupSession *session)
@@ -522,7 +511,7 @@ soup_session_get_local_address (SoupSession *session)
 }
 
 /**
- * soup_session_get_max_conns:
+ * soup_session_get_max_conns: (attributes org.gtk.Method.set_property=max-conns)
  * @session: a #SoupSession
  *
  * Get the maximum number of connections that @session can open at once.
@@ -541,10 +530,11 @@ soup_session_get_max_conns (SoupSession *session)
 }
 
 /**
- * soup_session_get_max_conns_per_host:
+ * soup_session_get_max_conns_per_host: (attributes org.gtk.Method.get_property=max-conns-per-host)
  * @session: a #SoupSession
  *
- * Get the maximum number of connections that @session can open at once to a given host.
+ * Get the maximum number of connections that @session can open at once to a
+ * given host.
  *
  * Returns: the maximum number of connections per host
  */
@@ -560,12 +550,14 @@ soup_session_get_max_conns_per_host (SoupSession *session)
 }
 
 /**
- * soup_session_set_proxy_resolver:
+ * soup_session_set_proxy_resolver: (attributes org.gtk.Method.set_property=proxy-resolver)
  * @session: a #SoupSession
  * @proxy_resolver: (nullable): a #GProxyResolver or %NULL
  *
- * Set a #GProxyResolver to be used by @session on new connections. If @proxy_resolver
- * is %NULL then no proxies will be used. See #SoupSession:proxy-resolver for more information.
+ * Set a [iface@Gio.ProxyResolver] to be used by @session on new connections.
+ *
+ * If @proxy_resolver is %NULL then no proxies will be used. See
+ * [property@Session:proxy-resolver] for more information.
  */
 void
 soup_session_set_proxy_resolver (SoupSession    *session,
@@ -588,13 +580,13 @@ soup_session_set_proxy_resolver (SoupSession    *session,
 }
 
 /**
- * soup_session_get_proxy_resolver:
+ * soup_session_get_proxy_resolver: (attributes org.gtk.Method.get_property=proxy-resolver)
  * @session: a #SoupSession
  *
- * Get the #GProxyResolver currently used by @session.
+ * Get the [iface@Gio.ProxyResolver] currently used by @session.
  *
  * Returns: (transfer none) (nullable): a #GProxyResolver or %NULL if proxies
- *    are disabled in @session
+ *   are disabled in @session
  */
 GProxyResolver *
 soup_session_get_proxy_resolver (SoupSession *session)
@@ -608,13 +600,14 @@ soup_session_get_proxy_resolver (SoupSession *session)
 }
 
 /**
- * soup_session_set_tls_database:
+ * soup_session_set_tls_database: (attributes org.gtk.Method.set_property=tls-database)
  * @session: a #SoupSession
- * @tls_database: (nullable): a #GTlsDatabase or %NULL
+ * @tls_database: (nullable): a #GTlsDatabase
  *
- * Set a #GTlsDatabase to be used by @session on new connections. If @tls_database
- * is %NULL then certificate validation will always fail. See #SoupSession:tls-database
- * for more information.
+ * Set a [class@GIo.TlsDatabase] to be used by @session on new connections.
+ *
+ * If @tls_database is %NULL then certificate validation will always fail. See
+ * [property@Session:tls-database] for more information.
  */
 void
 soup_session_set_tls_database (SoupSession  *session,
@@ -637,12 +630,12 @@ soup_session_set_tls_database (SoupSession  *session,
 }
 
 /**
- * soup_session_get_tls_database:
+ * soup_session_get_tls_database: (attributes org.gtk.Method.get_property=tls-database)
  * @session: a #SoupSession
  *
- * Get the #GTlsDatabase currently used by @session.
+ * Get the [class@Gio.TlsDatabase] currently used by @session.
  *
- * Returns: (transfer none) (nullable): a #GTlsDatabase or %NULL
+ * Returns: (transfer none) (nullable): a #GTlsDatabase
  */
 GTlsDatabase *
 soup_session_get_tls_database (SoupSession *session)
@@ -659,13 +652,16 @@ soup_session_get_tls_database (SoupSession *session)
 }
 
 /**
- * soup_session_set_tls_interaction:
+ * soup_session_set_tls_interaction: (attributes org.gtk.Method.set_property=tls-interaction)
  * @session: a #SoupSession
- * @tls_interaction: (nullable): a #GTlsInteraction or %NULL
+ * @tls_interaction: (nullable): a #GTlsInteraction
+ *
+ * Set a [class@Gio.TlsInteraction] to be used by @session on new connections.
  *
- * Set a #GTlsInteraction to be used by @session on new connections. If @tls_interaction
- * is %NULL then client certificate validation will always fail. See #SoupSession:tls-interaction
- * for more information.
+ * If @tls_interaction is %NULL then client certificate validation will always
+ * fail.
+ *
+ * See [property@Session:tls-interaction] for more information.
  */
 void
 soup_session_set_tls_interaction (SoupSession     *session,
@@ -687,12 +683,12 @@ soup_session_set_tls_interaction (SoupSession     *session,
 }
 
 /**
- * soup_session_get_tls_interaction:
+ * soup_session_get_tls_interaction: (attributes org.gtk.Method.get_property=tls-interaction)
  * @session: a #SoupSession
  *
- * Get the #GTlsInteraction currently used by @session.
+ * Get the [class@Gio.TlsInteraction] currently used by @session.
  *
- * Returns: (transfer none) (nullable): a #GTlsInteraction or %NULL
+ * Returns: (transfer none) (nullable): a #GTlsInteraction
  */
 GTlsInteraction *
 soup_session_get_tls_interaction (SoupSession *session)
@@ -706,12 +702,14 @@ soup_session_get_tls_interaction (SoupSession *session)
 }
 
 /**
- * soup_session_set_timeout:
+ * soup_session_set_timeout: (attributes org.gtk.Method.set_property=timeout)
  * @session: a #SoupSession
  * @timeout: a timeout in seconds
  *
  * Set a timeout in seconds for socket I/O operations to be used by @session
- * on new connections. See #SoupSession:timeout for more information.
+ * on new connections.
+ *
+ * See [property@Session:timeout] for more information.
  */
 void
 soup_session_set_timeout (SoupSession *session,
@@ -731,10 +729,11 @@ soup_session_set_timeout (SoupSession *session,
 }
 
 /**
- * soup_session_get_timeout:
+ * soup_session_get_timeout: (attributes org.gtk.Method.get_property=timeout)
  * @session: a #SoupSession
  *
- * Get the timeout in seconds for socket I/O operations currently used by @session.
+ * Get the timeout in seconds for socket I/O operations currently used by
+ * @session.
  *
  * Returns: the timeout in seconds
  */
@@ -750,12 +749,14 @@ soup_session_get_timeout (SoupSession *session)
 }
 
 /**
- * soup_session_set_idle_timeout:
+ * soup_session_set_idle_timeout: (attributes org.gtk.Method.set_property=idle-timeout)
  * @session: a #SoupSession
  * @timeout: a timeout in seconds
  *
  * Set a timeout in seconds for idle connection lifetime to be used by @session
- * on new connections. See #SoupSession:idle-timeout for more information.
+ * on new connections.
+ *
+ * See [property@Session:idle-timeout] for more information.
  */
 void
 soup_session_set_idle_timeout (SoupSession *session,
@@ -775,10 +776,11 @@ soup_session_set_idle_timeout (SoupSession *session,
 }
 
 /**
- * soup_session_get_idle_timeout:
+ * soup_session_get_idle_timeout: (attributes org.gtk.Method.get_property=idle-timeout)
  * @session: a #SoupSession
  *
- * Get the timeout in seconds for idle connection lifetime currently used by @session.
+ * Get the timeout in seconds for idle connection lifetime currently used by
+ * @session.
  *
  * Returns: the timeout in seconds
  */
@@ -794,15 +796,17 @@ soup_session_get_idle_timeout (SoupSession *session)
 }
 
 /**
- * soup_session_set_user_agent:
+ * soup_session_set_user_agent: (attributes org.gtk.Method.set_property=user-agent)
  * @session: a #SoupSession
  * @user_agent: the user agent string
  *
- * Set the value to use for the "User-Agent" header on #SoupMessage<!-- -->s sent from @session.
- * If @user_agent has trailing whitespace, @session will append its own product token
- * (eg, "<literal>libsoup/3.0.0</literal>") to the end of the header for you.
- * If @user_agent is %NULL then no "User-Agent" will be included in requests. See #SoupSession:user-agent
- * for more information.
+ * Set the value to use for the "User-Agent" header on [class@Message]s sent
+ * from @session.
+ *
+ * If @user_agent has trailing whitespace, @session will append its own product
+ * token (eg, `libsoup/3.0.0`) to the end of the header for you. If @user_agent
+ * is %NULL then no "User-Agent" will be included in requests. See
+ * [property@Session:user-agent] for more information.
  */
 void
 soup_session_set_user_agent (SoupSession *session,
@@ -844,12 +848,12 @@ soup_session_set_user_agent (SoupSession *session,
 }
 
 /**
- * soup_session_get_user_agent:
+ * soup_session_get_user_agent: (attributes org.gtk.Method.get_property=user-agent)
  * @session: a #SoupSession
  *
  * Get the value used by @session for the "User-Agent" header on new requests.
  *
- * Returns: (transfer none) (nullable): the user agent string or %NULL
+ * Returns: (transfer none) (nullable): the user agent string
  */
 const char *
 soup_session_get_user_agent (SoupSession *session)
@@ -863,13 +867,15 @@ soup_session_get_user_agent (SoupSession *session)
 }
 
 /**
- * soup_session_set_accept_language:
+ * soup_session_set_accept_language: (attributes org.gtk.Method.set_property=accept-language)
  * @session: a #SoupSession
  * @accept_language: the languages string
  *
- * Set the value to use for the "Accept-Language" header on #SoupMessage<!-- -->s sent from @session.
- * If @accept_language is %NULL then no "Accept-Language" will be included in requests. See #SoupSession:accept-language
- * for more information.
+ * Set the value to use for the "Accept-Language" header on [class@Message]s
+ * sent from @session.
+ *
+ * If @accept_language is %NULL then no "Accept-Language" will be included in
+ * requests. See [property@Session:accept-language] for more information.
  */
 void
 soup_session_set_accept_language (SoupSession *session,
@@ -894,12 +900,13 @@ soup_session_set_accept_language (SoupSession *session,
 }
 
 /**
- * soup_session_get_accept_language:
+ * soup_session_get_accept_language: (attributes org.gtk.Method.get_property=accept-language)
  * @session: a #SoupSession
  *
- * Get the value used by @session for the "Accept-Language" header on new requests.
+ * Get the value used by @session for the "Accept-Language" header on new
+ * requests.
  *
- * Returns: (transfer none) (nullable): the accept language string or %NULL
+ * Returns: (transfer none) (nullable): the accept language string
  */
 const char *
 soup_session_get_accept_language (SoupSession *session)
@@ -913,13 +920,15 @@ soup_session_get_accept_language (SoupSession *session)
 }
 
 /**
- * soup_session_set_accept_language_auto:
+ * soup_session_set_accept_language_auto: (attributes org.gtk.Method.set_property=accept-language-auto)
  * @session: a #SoupSession
  * @accept_language_auto: the value to set
  *
- * Set whether @session will automatically set the "Accept-Language" header on requests using
- * a value generated from system languages based on g_get_language_names(). See #SoupSession:accept-language-auto
- * for more information.
+ * Set whether @session will automatically set the "Accept-Language" header on
+ * requests using a value generated from system languages based on
+ * [func@GLib.get_language_names].
+ *
+ * See [property@Session:accept-language-auto] for more information.
  */
 void
 soup_session_set_accept_language_auto (SoupSession *session,
@@ -946,12 +955,14 @@ soup_session_set_accept_language_auto (SoupSession *session,
 }
 
 /**
- * soup_session_get_accept_language_auto:
+ * soup_session_get_accept_language_auto: (attributes org.gtk.Method.get_property=accept-language-auto)
  * @session: a #SoupSession
  *
- * Get whether @session automatically sets the "Accept-Language" header on new requests.
+ * Gets whether @session automatically sets the "Accept-Language" header on new
+ * requests.
  *
- * Returns: %TRUE if @session sets "Accept-Language" header automatically, or %FALSE otherwise.
+ * Returns: %TRUE if @session sets "Accept-Language" header automatically, or
+ *   %FALSE otherwise.
  */
 gboolean
 soup_session_get_accept_language_auto (SoupSession *session)
@@ -965,12 +976,12 @@ soup_session_get_accept_language_auto (SoupSession *session)
 }
 
 /**
- * soup_session_get_remote_connectable:
+ * soup_session_get_remote_connectable: (attributes org.gtk.Method.get_property=remote-connectable)
  * @session: a #SoupSession
  *
- * Get the remote connectable if one set.
+ * Gets the remote connectable if one set.
  *
- * Returns: (transfer none) (nullable): the #GSocketConnectable or %NULL
+ * Returns: (transfer none) (nullable): the #GSocketConnectable
  */
 GSocketConnectable *
 soup_session_get_remote_connectable (SoupSession *session)
@@ -1237,9 +1248,8 @@ soup_session_requeue_item (SoupSession          *session,
  * cause it to fail with %SOUP_STATUS_TOO_MANY_REDIRECTS.
  *
  * Returns: %TRUE if a redirection was applied, %FALSE if not
- * (eg, because there was no Location header, or it could not be
- * parsed).
- *
+ *   (eg, because there was no Location header, or it could not be
+ *   parsed).
  */
 static gboolean
 soup_session_redirect_message (SoupSession *session,
@@ -2135,8 +2145,7 @@ soup_session_requeue_message (SoupSession *session,
  * @session: a #SoupSession
  * @msg: a #SoupMessage currently running on @session
  *
- * Pauses HTTP I/O on @msg. Call soup_session_unpause_message() to
- * resume I/O.
+ * Pauses HTTP I/O on @msg. Call [method@Session.unpause_message] to resume I/O.
  **/
 void
 soup_session_pause_message (SoupSession *session,
@@ -2170,7 +2179,7 @@ soup_session_kick_queue (SoupSession *session)
  * @msg: a #SoupMessage currently running on @session
  *
  * Resumes HTTP I/O on @msg. Use this to resume after calling
- * soup_session_pause_message().
+ * [method@Session.pause_message].
  *
  * 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
@@ -2215,7 +2224,6 @@ soup_session_cancel_message (SoupSession *session,
  *
  * Cancels all pending requests in @session and closes all idle
  * persistent connections.
- *
  */
 void
 soup_session_abort (SoupSession *session)
@@ -2271,11 +2279,10 @@ feature_already_added (SoupSession *session, GType feature_type)
  * @feature: an object that implements #SoupSessionFeature
  *
  * Adds @feature's functionality to @session. You cannot add multiple
- * features of the same #GType to a session.
+ * features of the same [alias@GLib.Type] to a session.
  *
  * See the main #SoupSession documentation for information on what
  * features are present in sessions by default.
- *
  **/
 void
 soup_session_add_feature (SoupSession *session, SoupSessionFeature *feature)
@@ -2301,18 +2308,17 @@ soup_session_add_feature (SoupSession *session, SoupSessionFeature *feature)
  * @feature_type: a #GType
  *
  * If @feature_type is the type of a class that implements
- * #SoupSessionFeature, this creates a new feature of that type and
- * adds it to @session as with soup_session_add_feature(). You can use
+ * [iface@SessionFeature], this creates a new feature of that type and
+ * adds it to @session as with [method@Session.add_feature]. You can use
  * this when you don't need to customize the new feature in any way.
  * Adding multiple features of the same @feature_type is not allowed.
  *
- * If @feature_type is not a #SoupSessionFeature type, this gives each
+ * If @feature_type is not a [iface@SessionFeature] type, this gives each
  * existing feature on @session the chance to accept @feature_type as
- * a "subfeature". This can be used to add new #SoupAuth types, for instance.
+ * a "subfeature". This can be used to add new [class@Auth] types, for instance.
  *
  * See the main #SoupSession documentation for information on what
  * features are present in sessions by default.
- *
  **/
 void
 soup_session_add_feature_by_type (SoupSession *session, GType feature_type)
@@ -2349,7 +2355,6 @@ soup_session_add_feature_by_type (SoupSession *session, GType feature_type)
  * @feature: a feature that has previously been added to @session
  *
  * Removes @feature's functionality from @session.
- *
  **/
 void
 soup_session_remove_feature (SoupSession *session, SoupSessionFeature *feature)
@@ -2373,10 +2378,7 @@ soup_session_remove_feature (SoupSession *session, SoupSessionFeature *feature)
  * @feature_type: a #GType
  *
  * Removes all features of type @feature_type (or any subclass of
- * @feature_type) from @session. You can also remove standard features
- * from the session at construct time by using the
- * SoupSession:remove-feature-by-type property.
- *
+ * @feature_type) from @session.
  **/
 void
 soup_session_remove_feature_by_type (SoupSession *session, GType feature_type)
@@ -2411,11 +2413,10 @@ soup_session_remove_feature_by_type (SoupSession *session, GType feature_type)
  * @feature_type: the #GType of the class of features to check for
  *
  * Tests if @session has at a feature of type @feature_type (which can
- * be the type of either a #SoupSessionFeature, or else a subtype of
- * some class managed by another feature, such as #SoupAuth).
+ * be the type of either a [iface@SessionFeature], or else a subtype of
+ * some class managed by another feature, such as [class@Auth]).
  *
  * Returns: %TRUE or %FALSE
- *
  **/
 gboolean
 soup_session_has_feature (SoupSession *session,
@@ -2453,8 +2454,7 @@ soup_session_has_feature (SoupSession *session,
  * for @feature_type.)
  *
  * Returns: (transfer container) (element-type Soup.SessionFeature):
- * a list of features. You must free the list, but not its contents
- *
+ *   a list of features. You must free the list, but not its contents
  **/
 GSList *
 soup_session_get_features (SoupSession *session, GType feature_type)
@@ -2479,9 +2479,8 @@ soup_session_get_features (SoupSession *session, GType feature_type)
  *
  * Gets the feature in @session of type @feature_type.
  *
- * Returns: (nullable) (transfer none): a #SoupSessionFeature, or
- * %NULL. The feature is owned by @session.
- *
+ * Returns: (nullable) (transfer none): a #SoupSessionFeature, or %NULL. The
+ *   feature is owned by @session.
  **/
 SoupSessionFeature *
 soup_session_get_feature (SoupSession *session, GType feature_type)
@@ -2520,9 +2519,8 @@ soup_session_get_feature (SoupSession *session, GType feature_type)
  * Gets the feature in @session of type @feature_type, provided
  * that it is not disabled for @msg.
  *
- * Returns: (nullable) (transfer none): a #SoupSessionFeature, or %NULL. The
- * feature is owned by @session.
- *
+ * Returns: (nullable) (transfer none): a #SoupSessionFeature. The feature is
+ *   owned by @session.
  **/
 SoupSessionFeature *
 soup_session_get_feature_for_message (SoupSession *session, GType feature_type,
@@ -2605,17 +2603,17 @@ soup_session_class_init (SoupSessionClass *session_class)
 	 *
 	 * Emitted when a request is queued on @session.
 	 *
-	 * When sending a request, first #SoupSession::request_queued
+	 * When sending a request, first [signal@Session::request-queued]
 	 * is emitted, indicating that the session has become aware of
 	 * the request.
 	 *
 	 * After a connection is available to send the request various
-	 * #SoupMessage signals are emitted as the message is
+	 * [class@Message] signals are emitted as the message is
 	 * processed. If the message is requeued, it will emit
-	 * #SoupMessage::restarted, which will then be followed by other
-	 * #SoupMessage signals when the message is re-sent.
+	 * [signal@Message::restarted], which will then be followed by other
+	 * [class@Message] signals when the message is re-sent.
 	 *
-	 * Eventually, the message will emit #SoupMessage::finished.
+	 * Eventually, the message will emit [signal@Message::finished].
 	 * Normally, this signals the completion of message
 	 * processing. However, it is possible that the application
 	 * will requeue the message from the "finished" handler.
@@ -2623,15 +2621,14 @@ soup_session_class_init (SoupSessionClass *session_class)
 	 *
 	 * Eventually, a message will reach "finished" and not be
 	 * requeued. At that point, the session will emit
-	 * #SoupSession::request_unqueued to indicate that it is done
+	 * [signal@Session::request-unqueued] to indicate that it is done
 	 * with the message.
 	 *
-	 * To sum up: #SoupSession::request_queued and
-	 * #SoupSession::request_unqueued are guaranteed to be emitted
-	 * exactly once, but #SoupMessage::finished (and all of the
-	 * other #SoupMessage signals) may be invoked multiple times
-	 * for a given message.
-	 *
+	 * To sum up: [signal@Session::request-queued] and
+	 * [signal@Session::request-unqueued] are guaranteed to be emitted
+	 * exactly once, but [signal@Message::finished] (and all of the other
+	 * [class@Message] signals) may be invoked multiple times for a given
+	 * message.
 	 **/
 	signals[REQUEST_QUEUED] =
 		g_signal_new ("request-queued",
@@ -2649,10 +2646,10 @@ soup_session_class_init (SoupSessionClass *session_class)
 	 * @msg: the request that was unqueued
 	 *
 	 * Emitted when a request is removed from @session's queue,
-	 * indicating that @session is done with it. See
-	 * #SoupSession::request_queued for a detailed description of the
-	 * message lifecycle within a session.
+	 * indicating that @session is done with it.
 	 *
+	 * See [signal@Session::request-queued] for a detailed description of
+	 * the message lifecycle within a session.
 	 **/
 	signals[REQUEST_UNQUEUED] =
 		g_signal_new ("request-unqueued",
@@ -2666,16 +2663,15 @@ soup_session_class_init (SoupSessionClass *session_class)
 
 	/* properties */
 	/**
-	 * SoupSession:proxy-resolver:
+	 * SoupSession:proxy-resolver: (attributes org.gtk.Property.get=soup_session_get_proxy_resolver org.gtk.Property.set=soup_session_set_proxy_resolver)
 	 *
-	 * A #GProxyResolver to use with this session.
+	 * A [iface@Gio.ProxyResolver] to use with this session.
 	 *
 	 * If no proxy resolver is set, then the default proxy resolver
-	 * will be used. See g_proxy_resolver_get_default().
+	 * will be used. See [func@Gio.ProxyResolver.get_default].
 	 * You can set it to %NULL if you don't want to use proxies, or
-	 * set it to your own #GProxyResolver if you want to control
+	 * set it to your own [iface@Gio.ProxyResolver] if you want to control
 	 * what proxies get used.
-	 *
 	 */
         properties[PROP_PROXY_RESOLVER] =
 		g_param_spec_object ("proxy-resolver",
@@ -2685,7 +2681,7 @@ soup_session_class_init (SoupSessionClass *session_class)
 				     G_PARAM_READWRITE |
 				     G_PARAM_STATIC_STRINGS);
 	/**
-	 * SoupSession:max-conns:
+	 * SoupSession:max-conns: (attributes org.gtk.Property.get=soup_session_get_max_conns)
 	 *
 	 * The maximum number of connections that the session can open at once.
 	 */
@@ -2701,9 +2697,10 @@ soup_session_class_init (SoupSessionClass *session_class)
 				  G_PARAM_STATIC_STRINGS);
 
 	/**
-	 * SoupSession:max-conns-per-host:
+	 * SoupSession:max-conns-per-host: (attributes org.gtk.Property.get=soup_session_get_max_conns_per_host)
 	 *
-	 * The maximum number of connections that the session can open at once to a given host.
+	 * The maximum number of connections that the session can open at once
+	 * to a given host.
 	 */
         properties[PROP_MAX_CONNS_PER_HOST] =
 		g_param_spec_int ("max-conns-per-host",
@@ -2716,17 +2713,16 @@ soup_session_class_init (SoupSessionClass *session_class)
 				  G_PARAM_CONSTRUCT_ONLY |
 				  G_PARAM_STATIC_STRINGS);
 	/**
-	 * SoupSession:idle-timeout:
+	 * SoupSession:idle-timeout: (attributes org.gtk.Property.get=soup_session_get_idle_timeout org.gtk.Property.set=soup_session_set_idle_timeout)
 	 *
 	 * Connection lifetime (in seconds) when idle. Any connection
 	 * left idle longer than this will be closed.
 	 *
 	 * Although you can change this property at any time, it will
 	 * only affect newly-created connections, not currently-open
-	 * ones. You can call soup_session_abort() after setting this
+	 * ones. You can call [method@Session.abort] after setting this
 	 * if you want to ensure that all future connections will have
 	 * this timeout value.
-	 *
 	 **/
         properties[PROP_IDLE_TIMEOUT] =
 		g_param_spec_uint ("idle-timeout",
@@ -2737,14 +2733,13 @@ soup_session_class_init (SoupSessionClass *session_class)
 				   G_PARAM_STATIC_STRINGS);
 
 	/**
-	 * SoupSession:tls-database:
+	 * SoupSession:tls-database: (attributes org.gtk.Property.get=soup_session_get_tls_database org.gtk.Property.set=soup_session_set_tls_database)
 	 *
-	 * Sets the #GTlsDatabase to use for validating SSL/TLS
+	 * Sets the [class@Gio.TlsDatabase] to use for validating SSL/TLS
 	 * certificates.
 	 *
 	 * If no certificate database is set, then the default database will be
-	 * used. See g_tls_backend_get_default_database().
-	 *
+	 * used. See [method@Gio.TlsBackend.get_default_database].
 	 **/
         properties[PROP_TLS_DATABASE] =
 		g_param_spec_object ("tls-database",
@@ -2755,7 +2750,7 @@ soup_session_class_init (SoupSessionClass *session_class)
 				     G_PARAM_STATIC_STRINGS);
 
 	/**
-	 * SoupSession:timeout:
+	 * SoupSession:timeout: (attributes org.gtk.Property.get=soup_session_get_timeout org.gtk.Property.set=soup_session_set_timeout)
 	 *
 	 * The timeout (in seconds) for socket I/O operations
 	 * (including connecting to a server, and waiting for a reply
@@ -2763,11 +2758,11 @@ soup_session_class_init (SoupSessionClass *session_class)
 	 *
 	 * Although you can change this property at any time, it will
 	 * only affect newly-created connections, not currently-open
-	 * ones. You can call soup_session_abort() after setting this
+	 * ones. You can call [method@Session.abort] after setting this
 	 * if you want to ensure that all future connections will have
 	 * this timeout value.
 	 *
-	 * Not to be confused with #SoupSession:idle-timeout (which is
+	 * Not to be confused with [property@Session:idle-timeout] (which is
 	 * the length of time that idle persistent connections will be
 	 * kept open).
 	 */
@@ -2780,10 +2775,12 @@ soup_session_class_init (SoupSessionClass *session_class)
 				   G_PARAM_STATIC_STRINGS);
 
 	/**
-	 * SoupSession:user-agent:
+	 * SoupSession:user-agent: (attributes org.gtk.Property.get=soup_session_get_user_agent org.gtk.Property.set=soup_session_set_user_agent)
+	 *
+	 * User-Agent string.
 	 *
 	 * If non-%NULL, the value to use for the "User-Agent" header
-	 * on #SoupMessage<!-- -->s sent from this session.
+	 * on [class@Message]s sent from this session.
 	 *
 	 * RFC 2616 says: "The User-Agent request-header field
 	 * contains information about the user agent originating the
@@ -2801,9 +2798,9 @@ soup_session_class_init (SoupSessionClass *session_class)
 	 * followed by a version string. You may also put comments,
 	 * enclosed in parentheses, between or after the tokens.
 	 *
-	 * If you set a #SoupSession:user_agent property that has trailing
+	 * If you set a [property@Session:user-agent] property that has trailing
 	 * whitespace, #SoupSession will append its own product token
-	 * (eg, "<literal>libsoup/2.3.2</literal>") to the end of the
+	 * (eg, `libsoup/2.3.2`) to the end of the
 	 * header for you.
 	 **/
         properties[PROP_USER_AGENT] =
@@ -2815,13 +2812,12 @@ soup_session_class_init (SoupSessionClass *session_class)
 				     G_PARAM_STATIC_STRINGS);
 
 	/**
-	 * SoupSession:accept-language:
+	 * SoupSession:accept-language: (attributes org.gtk.Property.get=soup_session_get_accept_language org.gtk.Property.set=soup_session_set_accept_language)
 	 *
 	 * If non-%NULL, the value to use for the "Accept-Language" header
-	 * on #SoupMessage<!-- -->s sent from this session.
-	 *
-	 * Setting this will disable #SoupSession:accept-language-auto.
+	 * on [class@Message]s sent from this session.
 	 *
+	 * Setting this will disable [property@Session:accept-language-auto].
 	 **/
         properties[PROP_ACCEPT_LANGUAGE] =
 		g_param_spec_string ("accept-language",
@@ -2832,15 +2828,14 @@ soup_session_class_init (SoupSessionClass *session_class)
 				     G_PARAM_STATIC_STRINGS);
 
 	/**
-	 * SoupSession:accept-language-auto:
+	 * SoupSession:accept-language-auto: (attributes org.gtk.Property.get=soup_session_get_accept_language_auto org.gtk.Property.set=soup_session_set_accept_language_auto)
 	 *
 	 * If %TRUE, #SoupSession will automatically set the string
-	 * for the "Accept-Language" header on every #SoupMessage
-	 * sent, based on the return value of g_get_language_names().
+	 * for the "Accept-Language" header on every [class@Message]
+	 * sent, based on the return value of [func@GLib.get_language_names].
 	 *
 	 * Setting this will override any previous value of
-	 * #SoupSession:accept-language.
-	 *
+	 * [property@Session:accept-language].
 	 **/
         properties[PROP_ACCEPT_LANGUAGE_AUTO] =
 		g_param_spec_boolean ("accept-language-auto",
@@ -2851,7 +2846,7 @@ soup_session_class_init (SoupSessionClass *session_class)
 				      G_PARAM_STATIC_STRINGS);
 
 	/**
-	 * SoupSession:remote-connectable:
+	 * SoupSession:remote-connectable: (attributes org.gtk.Property.get=soup_session_get_remote_connectable)
 	 *
 	 * Sets a socket to make outgoing connections on. This will override the default
 	 * behaviour of opening TCP/IP sockets to the hosts specified in the URIs.
@@ -2859,8 +2854,7 @@ soup_session_class_init (SoupSessionClass *session_class)
 	 * This function is not required for common HTTP usage, but only when connecting
 	 * to a HTTP service that is not using standard TCP/IP sockets. An example of
 	 * this is a local service that uses HTTP over UNIX-domain sockets, in that case
-	 * a #GUnixSocketAddress can be passed to this function.
-	 *
+	 * a [class@Gio.UnixSocketAddress] can be passed to this function.
 	 **/
         properties[PROP_REMOTE_CONNECTABLE] =
 		g_param_spec_object ("remote-connectable",
@@ -2871,14 +2865,13 @@ soup_session_class_init (SoupSessionClass *session_class)
 				     G_PARAM_STATIC_STRINGS);
 
 	/**
-	 * SoupSession:local-address:
+	 * SoupSession:local-address: (attributes org.gtk.Property.get=soup_session_get_local_address)
 	 *
-	 * Sets the #GInetSocketAddress to use for the client side of
+	 * Sets the [class@Gio.InetSocketAddress] to use for the client side of
 	 * the connection.
 	 *
 	 * Use this property if you want for instance to bind the
 	 * local socket to a specific IP address.
-	 *
 	 **/
         properties[PROP_LOCAL_ADDRESS] =
 		g_param_spec_object ("local-address",
@@ -2889,12 +2882,12 @@ soup_session_class_init (SoupSessionClass *session_class)
 				     G_PARAM_STATIC_STRINGS);
 
 	/**
-	 * SoupSession:tls-interaction:
+	 * SoupSession:tls-interaction: (attributes org.gtk.Property.get=soup_session_get_tls_interaction org.gtk.Property.set=soup_session_set_tls_interaction)
 	 *
-	 * A #GTlsInteraction object that will be passed on to any
-	 * #GTlsConnections created by the session. (This can be used to
-	 * provide client-side certificates, for example.)
+	 * A [class@Gio.TlsInteraction] object that will be passed on to any
+	 * [class@Gio.TlsConnection]s created by the session.
 	 *
+	 * This can be used to provide client-side certificates, for example.
 	 **/
         properties[PROP_TLS_INTERACTION] =
 		g_param_spec_object ("tls-interaction",
@@ -3335,14 +3328,14 @@ soup_session_return_error_if_message_already_in_queue (SoupSession         *sess
  * @callback: (scope async): the callback to invoke
  * @user_data: data for @callback
  *
- * Asynchronously sends @msg and waits for the beginning of a
- * response. When @callback is called, then either @msg has been sent,
- * and its response headers received, or else an error has occurred.
- * Call soup_session_send_finish() to get a #GInputStream for reading
- * the response body.
+ * Asynchronously sends @msg and waits for the beginning of a response.
  *
- * See soup_session_send() for more details on the general semantics.
+ * When @callback is called, then either @msg has been sent, and its response
+ * headers received, or else an error has occurred. Call
+ * [method@Session.send_finish] to get a [class@Gio.InputStream] for reading the
+ * response body.
  *
+ * See [method@Session.send] for more details on the general semantics.
  */
 void
 soup_session_send_async (SoupSession         *session,
@@ -3381,13 +3374,13 @@ soup_session_send_async (SoupSession         *session,
  * @result: the #GAsyncResult passed to your callback
  * @error: return location for a #GError, or %NULL
  *
- * Gets the response to a soup_session_send_async() call and (if
- * successful), returns a #GInputStream that can be used to read the
+ * Gets the response to a [method@Session.send_async] call.
+ *
+ * If successful returns a [class@Gio.InputStream] that can be used to read the
  * response body.
  *
  * Returns: (transfer full): a #GInputStream for reading the
  *   response body, or %NULL on error.
- *
  */
 GInputStream *
 soup_session_send_finish (SoupSession   *session,
@@ -3425,27 +3418,26 @@ soup_session_send_finish (SoupSession   *session,
  * @error: return location for a #GError, or %NULL
  *
  * Synchronously sends @msg and waits for the beginning of a response.
- * On success, a #GInputStream will be returned which you can use to
+ *
+ * On success, a [class@Gio.InputStream] will be returned which you can use to
  * read the response body. ("Success" here means only that an HTTP
  * response was received and understood; it does not necessarily mean
  * that a 2xx class status code was received.)
  *
  * If non-%NULL, @cancellable can be used to cancel the request;
- * soup_session_send() will return a %G_IO_ERROR_CANCELLED error. Note
- * that with requests that have side effects (eg,
- * <literal>POST</literal>, <literal>PUT</literal>,
- * <literal>DELETE</literal>) it is possible that you might cancel the
- * request after the server acts on it, but before it returns a
- * response, leaving the remote resource in an unknown state.
+ * [method@Session.send] will return a %G_IO_ERROR_CANCELLED error. Note that
+ * with requests that have side effects (eg, `POST`, `PUT`, `DELETE`) it is
+ * possible that you might cancel the request after the server acts on it, but
+ * before it returns a response, leaving the remote resource in an unknown
+ * state.
  *
  * If @msg is requeued due to a redirect or authentication, the
- * initial (3xx/401/407) response body will be suppressed, and
- * soup_session_send() will only return once a final response has been
+ * initial (`3xx/401/407`) response body will be suppressed, and
+ * [method@Session.send] will only return once a final response has been
  * received.
  *
  * Returns: (transfer full): a #GInputStream for reading the
  *   response body, or %NULL on error.
- *
  */
 GInputStream *
 soup_session_send (SoupSession   *session,
@@ -3615,14 +3607,14 @@ send_and_read_stream_ready_cb (SoupSession  *session,
  * @user_data: data for @callback
  *
  * Asynchronously sends @msg and reads the response body.
+ *
  * When @callback is called, then either @msg has been sent, and its response
- * body read, or else an error has occurred.
- * This function should only be used when the resource to be retrieved
- * is not too long and can be stored in memory.
- * Call soup_session_send_and_read_finish() to get a #GBytes with the
- * response body.
+ * body read, or else an error has occurred. This function should only be used
+ * when the resource to be retrieved is not too long and can be stored in
+ * memory. Call [method@Session.send_and_read_finish] to get a
+ * [struct@GLib.Bytes] with the response body.
  *
- * See soup_session_send() for more details on the general semantics.
+ * See [method@Session.send] for more details on the general semantics.
  */
 void
 soup_session_send_and_read_async (SoupSession        *session,
@@ -3653,8 +3645,9 @@ soup_session_send_and_read_async (SoupSession        *session,
  * @result: the #GAsyncResult passed to your callback
  * @error: return location for a #GError, or %NULL
  *
- * Gets the response to a soup_session_send_and_read_async() call and (if
- * successful), returns a #GBytes with the response body.
+ * Gets the response to a [method@Session.send_and_read_async].
+ *
+ * If successful, returns a [struct@GLib.Bytes] with the response body.
  *
  * Returns: (transfer full): a #GBytes, or %NULL on error.
  */
@@ -3677,11 +3670,12 @@ soup_session_send_and_read_finish (SoupSession  *session,
  * @error: return location for a #GError, or %NULL
  *
  * Synchronously sends @msg and reads the response body.
- * On success, a #GBytes will be returned with the response body.
+ *
+ * On success, a [struct@GLib.Bytes] will be returned with the response body.
  * This function should only be used when the resource to be retrieved
  * is not too long and can be stored in memory.
  *
- * See soup_session_send() for more details on the general semantics.
+ * See [method@Session.send] for more details on the general semantics.
  *
  * Returns: (transfer full): a #GBytes, or %NULL on error.
  */
@@ -3718,12 +3712,12 @@ soup_session_send_and_read (SoupSession  *session,
  * @session: a #SoupSession
  * @result: the #GAsyncResult passed to your callback
  *
- * Gets the #SoupMessage of the @result asynchronous operation
- * This is useful to get the #SoupMessage of an asynchronous
- * operation started by @session from its #GAsyncReadyCallback.
+ * Gets the [class@Message] of the @result asynchronous operation This is useful
+ * to get the [class@Message] of an asynchronous operation started by @session
+ * from its [callback@Gio.AsyncReadyCallback].
  *
  * Returns: (transfer none) (nullable): a #SoupMessage or
- *    %NULL if @result is not a valid @session async operation result.
+ *   %NULL if @result is not a valid @session async operation result.
  */
 SoupMessage *
 soup_session_get_async_result_message (SoupSession  *session,
@@ -3765,9 +3759,10 @@ steal_connection (SoupSession          *session,
  * @msg: the message whose connection is to be stolen
  *
  * "Steals" the HTTP connection associated with @msg from @session.
+ *
  * This happens immediately, regardless of the current state of the
  * connection, and @msg's callback will not be called. You can steal
- * the connection from a #SoupMessage signal handler if you need to
+ * the connection from a [class@Message] signal handler if you need to
  * wait for part or all of the response to be received first.
  *
  * Calling this function may cause @msg to be freed if you are not
@@ -3777,7 +3772,6 @@ steal_connection (SoupSession          *session,
  *   with @msg (or %NULL if @msg was no longer associated with a
  *   connection). No guarantees are made about what kind of #GIOStream
  *   is returned.
- *
  */
 static GIOStream *
 soup_session_steal_connection (SoupSession *session,
@@ -3881,8 +3875,8 @@ websocket_connect_async_stop (SoupMessage *msg, gpointer user_data)
  * @callback: (scope async): the callback to invoke
  * @user_data: data for @callback
  *
- * Asynchronously creates a #SoupWebsocketConnection to communicate
- * with a remote server.
+ * Asynchronously creates a [class@WebsocketConnection] to communicate with a
+ * remote server.
  *
  * All necessary WebSocket-related headers will be added to @msg, and
  * it will then be sent and asynchronously processed normally
@@ -3891,15 +3885,13 @@ websocket_connect_async_stop (SoupMessage *msg, gpointer user_data)
  * If the server returns "101 Switching Protocols", then @msg's status
  * code and response headers will be updated, and then the WebSocket
  * handshake will be completed. On success,
- * soup_session_websocket_connect_finish() will return a new
- * #SoupWebsocketConnection. On failure it will return a #GError.
+ * [method@Session.websocket_connect_finish] will return a new
+ * [class@WebsocketConnection]. On failure it will return a #GError.
  *
- * If the server returns a status other than "101 Switching
- * Protocols", then @msg will contain the complete response headers
- * and body from the server's response, and
- * soup_session_websocket_connect_finish() will return
+ * If the server returns a status other than "101 Switching Protocols", then
+ * @msg will contain the complete response headers and body from the server's
+ * response, and [method@Session.websocket_connect_finish] will return
  * %SOUP_WEBSOCKET_ERROR_NOT_WEBSOCKET.
- *
  */
 void
 soup_session_websocket_connect_async (SoupSession          *session,
@@ -3958,14 +3950,14 @@ soup_session_websocket_connect_async (SoupSession          *session,
  * @result: the #GAsyncResult passed to your callback
  * @error: return location for a #GError, or %NULL
  *
- * Gets the #SoupWebsocketConnection response to a
- * soup_session_websocket_connect_async() call and (if successful),
- * returns a #SoupWebsocketConnection that can be used to communicate
- * with the server.
+ * Gets the [class@WebsocketConnection] response to a
+ * [method@Session.websocket_connect_async] call.
+ *
+ * If successful, returns a [class@WebsocketConnection] that can be used to
+ * communicate with the server.
  *
  * Returns: (transfer full): a new #SoupWebsocketConnection, or
  *   %NULL on error.
- *
  */
 SoupWebsocketConnection *
 soup_session_websocket_connect_finish (SoupSession      *session,
@@ -4016,12 +4008,15 @@ preconnect_async_complete (SoupMessage *msg,
  * @callback: (nullable) (scope async): the callback to invoke when the operation finishes
  * @user_data: data for @progress_callback and @callback
  *
- * Start a preconnection to @msg. Once the connection is done, it will remain in idle state so that
- * it can be reused by future requests. If there's already an idle connection for the given @msg
- * host, the operation finishes successfully without creating a new connection. If a new request
- * for the given @msg host is made while the preconnect is still ongoing, the request will take
- * the ownership of the connection and the preconnect operation will finish successfully (if
- * there's a connection error it will be handled by the request).
+ * Start a preconnection to @msg.
+ *
+ * Once the connection is done, it will remain in idle state so that it can be
+ * reused by future requests. If there's already an idle connection for the
+ * given @msg host, the operation finishes successfully without creating a new
+ * connection. If a new request for the given @msg host is made while the
+ * preconnect is still ongoing, the request will take the ownership of the
+ * connection and the preconnect operation will finish successfully (if there's
+ * a connection error it will be handled by the request).
  *
  * The operation finishes when the connection is done or an error occurred.
  */
@@ -4064,7 +4059,7 @@ soup_session_preconnect_async (SoupSession        *session,
  * @result: the #GAsyncResult passed to your callback
  * @error: return location for a #GError, or %NULL
  *
- * Complete a preconnect async operation started with soup_session_preconnect_async().
+ * Complete a preconnect async operation started with [method@Session.preconnect_async].
  *
  * Return value: %TRUE if the preconnect succeeded, or %FALSE in case of error.
  */
diff --git a/libsoup/soup-status.c b/libsoup/soup-status.c
index 3817ad4b..1eb8e088 100644
--- a/libsoup/soup-status.c
+++ b/libsoup/soup-status.c
@@ -13,14 +13,6 @@
 #include "soup.h"
 
 /**
- * SECTION:soup-status
- * @section_id: SoupStatus
- * @short_description: HTTP (and libsoup) status codes
- *
- * HTTP (and libsoup) status codes.
- **/
-
-/**
  * SOUP_STATUS_IS_INFORMATIONAL:
  * @status: an HTTP status code
  *
@@ -224,10 +216,10 @@ static const struct {
  *
  * Looks up the stock HTTP description of @status_code.
  *
- * <emphasis>There is no reason for you to ever use this
- * function.</emphasis> If you wanted the textual description for the
- * #SoupMessage:status_code of a given #SoupMessage, you should just
- * look at the message's #SoupMessage:reason_phrase. However, you
+ * *There is no reason for you to ever use this
+ * function.* If you wanted the textual description for the
+ * [property@Message:status-code] of a given [class@Message], you should just
+ * look at the message's [property@Message:reason-phrase]. However, you
  * should only do that for use in debugging messages; HTTP reason
  * phrases are not localized, and are not generally very descriptive
  * anyway, and so they should never be presented to the user directly.
diff --git a/libsoup/soup-tld.c b/libsoup/soup-tld.c
index e9474864..2d815166 100644
--- a/libsoup/soup-tld.c
+++ b/libsoup/soup-tld.c
@@ -17,16 +17,6 @@
 #include "soup-tld.h"
 #include "soup.h"
 
-/**
- * SECTION:soup-tld
- * @section_id: SoupTLD
- * @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 const char *soup_tld_get_base_domain_internal (const char *hostname,
 						      GError    **error);
 
@@ -36,10 +26,11 @@ static const char *soup_tld_get_base_domain_internal (const char *hostname,
  * @error: return location for a #GError, or %NULL to ignore
  *   errors. See #SoupTLDError for the available error codes
  *
- * Finds the base domain for a given @hostname. The base domain is
- * composed by the top level domain (such as .org, .com, .co.uk, etc)
- * plus the second level domain, for example for myhost.mydomain.com
- * it will return mydomain.com.
+ * Finds the base domain for a given @hostname
+ *
+ * The base domain is composed by the top level domain (such as .org, .com,
+ * .co.uk, etc) plus the second level domain, for example for
+ * myhost.mydomain.com it will return mydomain.com.
  *
  * Note that %NULL will be returned for private URLs (those not ending
  * with any well known TLD) because choosing a base domain for them
@@ -51,8 +42,7 @@ static const char *soup_tld_get_base_domain_internal (const char *hostname,
  * format).
  *
  * Returns: a pointer to the start of the base domain in @hostname. If
- * an error occurs, %NULL will be returned and @error set.
- *
+ *   an error occurs, %NULL will be returned and @error set.
  **/
 const char *
 soup_tld_get_base_domain (const char *hostname, GError **error)
@@ -85,7 +75,6 @@ soup_psl_context (void)
  * UTF-8 or ASCII format.
  *
  * Returns: %TRUE if it is a public domain, %FALSE otherwise.
- *
  **/
 gboolean
 soup_tld_domain_is_public_suffix (const char *domain)
@@ -106,7 +95,6 @@ soup_tld_domain_is_public_suffix (const char *domain)
  * SOUP_TLD_ERROR:
  *
  * The #GError domain for soup-tld-related errors.
- *
  */
 /**
  * SoupTLDError:
@@ -117,14 +105,13 @@ soup_tld_domain_is_public_suffix (const char *domain)
  *   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>.
+ *   [func@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.
- *
  */
 
 G_DEFINE_QUARK (soup-tld-error-quark, soup_tld_error)
diff --git a/libsoup/soup-uri-utils.c b/libsoup/soup-uri-utils.c
index 8fea9a63..d317bea6 100644
--- a/libsoup/soup-uri-utils.c
+++ b/libsoup/soup-uri-utils.c
@@ -33,15 +33,6 @@
 #include "soup-misc.h"
 
 /**
- * SECTION:soup-uri-utils
- * @section_id: SoupURIUtils
- * @title: URI Utilities
- * @short_description: Functions to help working with #GUri and HTTP
- *
- * Utility functions and defines to help working with URIs.
- */
-
-/**
  * SOUP_HTTP_URI_FLAGS:
  *
  * The set of #GUriFlags libsoup expects all #GUri to use.
@@ -99,7 +90,7 @@ flags_equal (GUriFlags flags1, GUriFlags flags2)
  * @uri1: a #GUri
  * @uri2: another #GUri
  *
- * Tests whether or not @uri1 and @uri2 are equal in all parts
+ * Tests whether or not @uri1 and @uri2 are equal in all parts.
  *
  * Returns: %TRUE if equal otherwise %FALSE
  **/
@@ -150,9 +141,10 @@ soup_uri_get_path_and_query (GUri *uri)
  * soup_uri_uses_default_port:
  * @uri: a #GUri
  *
- * Tests if @uri uses the default port for its scheme. (Eg, 80 for
- * http.) (This only works for http, https and ftp; libsoup does not know
- * the default ports of other protocols.)
+ * Tests if @uri uses the default port for its scheme.
+ *
+ * (Eg, 80 for http.) (This only works for http, https and ftp; libsoup does not
+ * know the default ports of other protocols.)
  *
  * Returns: %TRUE or %FALSE
  **/
@@ -278,7 +270,7 @@ soup_uri_is_http (GUri *uri)
 /**
  * soup_uri_decode_data_uri:
  * @uri: a data URI, in string form
- * @content_type: (out) (nullable) (transfer full): location to store content type, or %NULL
+ * @content_type: (out) (nullable) (transfer full): location to store content type
  *
  * Decodes the given data URI and returns its contents and @content_type.
  *
@@ -367,7 +359,7 @@ soup_uri_decode_data_uri (const char *uri,
  * @SOUP_URI_QUERY: the URI query component
  * @SOUP_URI_FRAGMENT: the URI fragment component
  *
- * Enum values passed to soup_uri_copy() to indicate the components of
+ * Enum values passed to [func@uri_copy] to indicate the components of
  * the URI that should be updated with the given values.
  */
 
@@ -378,7 +370,7 @@ soup_uri_decode_data_uri (const char *uri,
  * @...: value of @first_component  followed by additional
  *    components and values, terminated by %SOUP_URI_NONE
  *
- * Return a copy of @uri with the given components updated
+ * Return a copy of @uri with the given components updated.
  *
  * Returns: (transfer full): a new #GUri
  */
diff --git a/libsoup/soup-version.c b/libsoup/soup-version.c
index 23d1118e..28088496 100644
--- a/libsoup/soup-version.c
+++ b/libsoup/soup-version.c
@@ -12,26 +12,18 @@
 #include "soup-version.h"
 
 /**
- * SECTION:soup-version
- * @section_id: SoupVersion
- * @short_description: Variables and functions to check the libsoup version
- *
- * Variables and functions to check the libsoup version.
- **/
-
-/**
  * SOUP_MAJOR_VERSION:
  *
- * Like soup_get_major_version(), but from the headers used at
- * application compile time, rather than from the library linked
- * against at application run time.
+ * Like [func@get_major_version], but from the headers used at application
+ * compile time, rather than from the library linked against at application run
+ * time.
  *
  */
 
 /**
  * SOUP_MINOR_VERSION:
  *
- * Like soup_get_minor_version(), but from the headers used at
+ * Like [func@get_minor_version], but from the headers used at
  * application compile time, rather than from the library linked
  * against at application run time.
  *
@@ -40,7 +32,7 @@
 /**
  * SOUP_MICRO_VERSION:
  *
- * Like soup_get_micro_version(), but from the headers used at
+ * Like [func@get_micro_version], but from the headers used at
  * application compile time, rather than from the library linked
  * against at application run time.
  *
@@ -54,16 +46,16 @@
  *
  * Macro to test the version of libsoup being compiled against.
  *
- * Returns: %TRUE if the version of the libsoup header files
+ * Returns %TRUE if the version of the libsoup header files
  * is the same as or newer than the passed-in version.
- *
  */
 
 /**
  * soup_get_major_version:
  *
  * Returns the major version number of the libsoup library.
- * (e.g. in libsoup version 2.42.0 this is 2.)
+ *
+ * e.g. in libsoup version 2.42.0 this is 2.
  *
  * This function is in the library, so it represents the libsoup library
  * your code is running against. Contrast with the #SOUP_MAJOR_VERSION
@@ -71,7 +63,6 @@
  * have included when compiling your code.
  *
  * Returns: the major version number of the libsoup library
- *
  */
 guint
 soup_get_major_version (void)
@@ -83,7 +74,8 @@ soup_get_major_version (void)
  * soup_get_minor_version:
  *
  * Returns the minor version number of the libsoup library.
- * (e.g. in libsoup version 2.42.0 this is 42.)
+ *
+ * e.g. in libsoup version 2.42.0 this is 42.
  *
  * This function is in the library, so it represents the libsoup library
  * your code is running against. Contrast with the #SOUP_MINOR_VERSION
@@ -91,7 +83,6 @@ soup_get_major_version (void)
  * have included when compiling your code.
  *
  * Returns: the minor version number of the libsoup library
- *
  */
 guint
 soup_get_minor_version (void)
@@ -103,7 +94,8 @@ soup_get_minor_version (void)
  * soup_get_micro_version:
  *
  * Returns the micro version number of the libsoup library.
- * (e.g. in libsoup version 2.42.0 this is 0.)
+ *
+ * e.g. in libsoup version 2.42.0 this is 0.
  *
  * This function is in the library, so it represents the libsoup library
  * your code is running against. Contrast with the #SOUP_MICRO_VERSION
@@ -111,7 +103,6 @@ soup_get_minor_version (void)
  * have included when compiling your code.
  *
  * Returns: the micro version number of the libsoup library
- *
  */
 guint
 soup_get_micro_version (void)
@@ -125,14 +116,14 @@ soup_get_micro_version (void)
  * @minor: the minor version to check
  * @micro: the micro version to check
  *
- * Like SOUP_CHECK_VERSION, but the check for soup_check_version is
- * at runtime instead of compile time. This is useful for compiling
- * against older versions of libsoup, but using features from newer
- * versions.
+ * Like [func@CHECK_VERSION], but the check for soup_check_version is
+ * at runtime instead of compile time.
  *
- * Returns: %TRUE if the version of the libsoup currently loaded
- * is the same as or newer than the passed-in version.
+ * This is useful for compiling against older versions of libsoup, but using
+ * features from newer versions.
  *
+ * Returns: %TRUE if the version of the libsoup currently loaded
+ *   is the same as or newer than the passed-in version.
  */
 gboolean
 soup_check_version (guint major,
@@ -146,7 +137,9 @@ soup_check_version (guint major,
  * SOUP_VERSION_MIN_REQUIRED:
  *
  * A macro that should be defined by the user prior to including
- * libsoup.h. The definition should be one of the predefined libsoup
+ * `libsoup.h`.
+ *
+ * The definition should be one of the predefined libsoup
  * version macros: %SOUP_VERSION_2_24, %SOUP_VERSION_2_26, ...
  *
  * This macro defines the earliest version of libsoup that the package
@@ -156,14 +149,15 @@ soup_check_version (guint major,
  * functions, then using functions that were deprecated in version
  * %SOUP_VERSION_MIN_REQUIRED or earlier will cause warnings (but
  * using functions deprecated in later releases will not).
- *
  */
 
 /**
  * SOUP_VERSION_MAX_ALLOWED:
  *
  * A macro that should be defined by the user prior to including
- * libsoup.h. The definition should be one of the predefined libsoup
+ * libsoup.h.
+ *
+ * The definition should be one of the predefined libsoup
  * version macros: %SOUP_VERSION_2_24, %SOUP_VERSION_2_26, ...
  *
  * This macro defines the latest version of the libsoup API that the
@@ -173,8 +167,7 @@ soup_check_version (guint major,
  * functions, then using functions added after version
  * %SOUP_VERSION_MAX_ALLOWED will cause warnings.
  *
- * Unless you are using SOUP_CHECK_VERSION() or the like to compile
+ * Unless you are using [func@CHECK_VERSION] or the like to compile
  * different code depending on the libsoup version, then this should be
  * set to the same value as %SOUP_VERSION_MIN_REQUIRED.
- *
  */
diff --git a/libsoup/websocket/soup-websocket-connection.c b/libsoup/websocket/soup-websocket-connection.c
index a46bcaaa..fcd4fd36 100644
--- a/libsoup/websocket/soup-websocket-connection.c
+++ b/libsoup/websocket/soup-websocket-connection.c
@@ -29,48 +29,40 @@
 #include "soup-websocket-extension.h"
 
 /*
- * SECTION:websocketconnection
- * @title: SoupWebsocketConnection
- * @short_description: A WebSocket connection
+ * SoupWebsocketConnection:
+ *
+ * A WebSocket connection.
  *
  * A #SoupWebsocketConnection is a WebSocket connection to a peer.
  * This API is modeled after the W3C API for interacting with
  * WebSockets.
  *
- * The #SoupWebsocketConnection:state property will indicate the
+ * The [property@WebsocketConnection:state] property will indicate the
  * state of the connection.
  *
- * Use soup_websocket_connection_send() to send a message to the peer.
- * When a message is received the #SoupWebsocketConnection::message
+ * Use [method@WebsocketConnection.send] to send a message to the peer.
+ * When a message is received the [signal@WebsocketConnection::message]
  * signal will fire.
  *
- * The soup_websocket_connection_close() function will perform an
+ * The [method@WebsocketConnection.close] function will perform an
  * orderly close of the connection. The
- * #SoupWebsocketConnection::closed signal will fire once the
+ * [signal@WebsocketConnection::closed] signal will fire once the
  * connection closes, whether it was initiated by this side or the
  * peer.
  *
- * Connect to the #SoupWebsocketConnection::closing signal to detect
+ * Connect to the [signal@WebsocketConnection::closing] signal to detect
  * when either peer begins closing the connection.
  */
 
 /**
- * SoupWebsocketConnection:
- *
- * A class representing a WebSocket connection.
- *
- */
-
-/**
  * SoupWebsocketConnectionClass:
- * @message: default handler for the #SoupWebsocketConnection::message signal
- * @error: default handler for the #SoupWebsocketConnection::error signal
- * @closing: the default handler for the #SoupWebsocketConnection:closing signal
- * @closed: default handler for the #SoupWebsocketConnection::closed signal
- * @pong: default handler for the #SoupWebsocketConnection::pong signal
- *
- * The abstract base class for #SoupWebsocketConnection
+ * @message: default handler for the [signal@WebsocketConnection::message] signal
+ * @error: default handler for the [signal@WebsocketConnection::error] signal
+ * @closing: the default handler for the [signal@WebsocketConnection:closing] signal
+ * @closed: default handler for the [signal@WebsocketConnection::closed] signal
+ * @pong: default handler for the [signal@WebsocketConnection::pong] signal
  *
+ * The abstract base class for [class@WebsocketConnection].
  */
 
 enum {
@@ -1486,7 +1478,6 @@ soup_websocket_connection_class_init (SoupWebsocketConnectionClass *klass)
 	 * over.
 	 *
 	 * The input and output streams must be pollable streams.
-	 *
 	 */
         properties[PROP_IO_STREAM] =
                 g_param_spec_object ("io-stream",
@@ -1501,7 +1492,6 @@ soup_websocket_connection_class_init (SoupWebsocketConnectionClass *klass)
 	 * SoupWebsocketConnection:connection-type:
 	 *
 	 * The type of connection (client/server).
-	 *
 	 */
         properties[PROP_CONNECTION_TYPE] =
                 g_param_spec_enum ("connection-type",
@@ -1520,7 +1510,6 @@ soup_websocket_connection_class_init (SoupWebsocketConnectionClass *klass)
 	 *
 	 * For servers this represents the address of the WebSocket,
 	 * and for clients it is the address connected to.
-	 *
 	 */
         properties[PROP_URI] =
                 g_param_spec_boxed ("uri",
@@ -1535,7 +1524,6 @@ soup_websocket_connection_class_init (SoupWebsocketConnectionClass *klass)
 	 * SoupWebsocketConnection:origin:
 	 *
 	 * The client's Origin.
-	 *
 	 */
         properties[PROP_ORIGIN] =
                 g_param_spec_string ("origin",
@@ -1551,7 +1539,6 @@ soup_websocket_connection_class_init (SoupWebsocketConnectionClass *klass)
 	 *
 	 * The chosen protocol, or %NULL if a protocol was not agreed
 	 * upon.
-	 *
 	 */
         properties[PROP_PROTOCOL] =
                 g_param_spec_string ("protocol",
@@ -1566,7 +1553,6 @@ soup_websocket_connection_class_init (SoupWebsocketConnectionClass *klass)
 	 * SoupWebsocketConnection:state:
 	 *
 	 * The current state of the WebSocket.
-	 *
 	 */
         properties[PROP_STATE] =
                 g_param_spec_enum ("state",
@@ -1580,9 +1566,9 @@ soup_websocket_connection_class_init (SoupWebsocketConnectionClass *klass)
 	/**
 	 * SoupWebsocketConnection:max-incoming-payload-size:
 	 *
-	 * The maximum payload size for incoming packets the protocol expects
-	 * or 0 to not limit it.
+	 * The maximum payload size for incoming packets.
 	 *
+	 * The protocol expects or 0 to not limit it.
 	 */
         properties[PROP_MAX_INCOMING_PAYLOAD_SIZE] =
                 g_param_spec_uint64 ("max-incoming-payload-size",
@@ -1599,9 +1585,9 @@ soup_websocket_connection_class_init (SoupWebsocketConnectionClass *klass)
 	 * SoupWebsocketConnection:keepalive-interval:
 	 *
 	 * Interval in seconds on when to send a ping message which will
-	 * serve as a keepalive message. If set to 0 the keepalive message is
-	 * disabled.
+	 * serve as a keepalive message.
 	 *
+	 * If set to 0 the keepalive message is disabled.
 	 */
         properties[PROP_KEEPALIVE_INTERVAL] =
                 g_param_spec_uint ("keepalive-interval",
@@ -1617,8 +1603,7 @@ soup_websocket_connection_class_init (SoupWebsocketConnectionClass *klass)
         /**
          * SoupWebsocketConnection:extensions:
          *
-         * List of #SoupWebsocketExtension objects that are active in the connection.
-         *
+         * List of [class@WebsocketExtension] objects that are active in the connection.
          */
         properties[PROP_EXTENSIONS] =
                 g_param_spec_pointer ("extensions",
@@ -1639,9 +1624,8 @@ soup_websocket_connection_class_init (SoupWebsocketConnectionClass *klass)
 	 * Emitted when we receive a message from the peer.
 	 *
 	 * As a convenience, the @message data will always be
-	 * NUL-terminated, but the NUL byte will not be included in
+	 * %NULL-terminated, but the NUL byte will not be included in
 	 * the length count.
-	 *
 	 */
 	signals[MESSAGE] = g_signal_new ("message",
 					 SOUP_TYPE_WEBSOCKET_CONNECTION,
@@ -1655,10 +1639,10 @@ soup_websocket_connection_class_init (SoupWebsocketConnectionClass *klass)
 	 * @self: the WebSocket
 	 * @error: the error that occured
 	 *
-	 * Emitted when an error occurred on the WebSocket. This may
-	 * be fired multiple times. Fatal errors will be followed by
-	 * the #SoupWebsocketConnection::closed signal being emitted.
+	 * Emitted when an error occurred on the WebSocket.
 	 *
+	 * This may be fired multiple times. Fatal errors will be followed by
+	 * the [signal@WebsocketConnection::closed] signal being emitted.
 	 */
 	signals[ERROR] = g_signal_new ("error",
 				       SOUP_TYPE_WEBSOCKET_CONNECTION,
@@ -1672,7 +1656,6 @@ soup_websocket_connection_class_init (SoupWebsocketConnectionClass *klass)
 	 * @self: the WebSocket
 	 *
 	 * This signal will be emitted during an orderly close.
-	 *
 	 */
 	signals[CLOSING] = g_signal_new ("closing",
 					 SOUP_TYPE_WEBSOCKET_CONNECTION,
@@ -1685,13 +1668,13 @@ soup_websocket_connection_class_init (SoupWebsocketConnectionClass *klass)
 	 * SoupWebsocketConnection::closed:
 	 * @self: the WebSocket
 	 *
-	 * Emitted when the connection has completely closed, either
-	 * due to an orderly close from the peer, one initiated via
-	 * soup_websocket_connection_close() or a fatal error
+	 * Emitted when the connection has completely closed.
+	 *
+	 * This happens either due to an orderly close from the peer, one
+	 * initiated via [method@WebsocketConnection.close] or a fatal error
 	 * condition that caused a close.
 	 *
 	 * This signal will be emitted once.
-	 *
 	 */
 	signals[CLOSED] = g_signal_new ("closed",
 					SOUP_TYPE_WEBSOCKET_CONNECTION,
@@ -1709,9 +1692,8 @@ soup_websocket_connection_class_init (SoupWebsocketConnectionClass *klass)
 	 * unsolicited) from the peer.
 	 *
 	 * As a convenience, the @message data will always be
-	 * NUL-terminated, but the NUL byte will not be included in
+	 * %NULL-terminated, but the NUL byte will not be included in
 	 * the length count.
-	 *
 	 */
 	signals[PONG] = g_signal_new ("pong",
 				      SOUP_TYPE_WEBSOCKET_CONNECTION,
@@ -1731,6 +1713,7 @@ soup_websocket_connection_class_init (SoupWebsocketConnectionClass *klass)
  * @extensions: (element-type SoupWebsocketExtension) (transfer full): a #GList of #SoupWebsocketExtension objects
  *
  * Creates a #SoupWebsocketConnection on @stream with the given active @extensions.
+ *
  * This should be called after completing the handshake to begin using the WebSocket
  * protocol.
  *
@@ -1765,7 +1748,6 @@ soup_websocket_connection_new (GIOStream                    *stream,
  * Get the I/O stream the WebSocket is communicating over.
  *
  * Returns: (transfer none): the WebSocket's I/O stream.
- *
  */
 GIOStream *
 soup_websocket_connection_get_io_stream (SoupWebsocketConnection *self)
@@ -1784,7 +1766,6 @@ soup_websocket_connection_get_io_stream (SoupWebsocketConnection *self)
  * Get the connection type (client/server) of the connection.
  *
  * Returns: the connection type
- *
  */
 SoupWebsocketConnectionType
 soup_websocket_connection_get_connection_type (SoupWebsocketConnection *self)
@@ -1806,7 +1787,6 @@ soup_websocket_connection_get_connection_type (SoupWebsocketConnection *self)
  * for clients it is the address connected to.
  *
  * Returns: (transfer none): the URI
- *
  */
 GUri *
 soup_websocket_connection_get_uri (SoupWebsocketConnection *self)
@@ -1824,8 +1804,7 @@ soup_websocket_connection_get_uri (SoupWebsocketConnection *self)
  *
  * Get the origin of the WebSocket.
  *
- * Returns: (nullable): the origin, or %NULL
- *
+ * Returns: (nullable): the origin
  */
 const char *
 soup_websocket_connection_get_origin (SoupWebsocketConnection *self)
@@ -1843,8 +1822,7 @@ soup_websocket_connection_get_origin (SoupWebsocketConnection *self)
  *
  * Get the protocol chosen via negotiation with the peer.
  *
- * Returns: (nullable): the chosen protocol, or %NULL
- *
+ * Returns: (nullable): the chosen protocol
  */
 const char *
 soup_websocket_connection_get_protocol (SoupWebsocketConnection *self)
@@ -1863,7 +1841,6 @@ soup_websocket_connection_get_protocol (SoupWebsocketConnection *self)
  * Get the extensions chosen via negotiation with the peer.
  *
  * Returns: (element-type SoupWebsocketExtension) (transfer none): a #GList of #SoupWebsocketExtension objects
- *
  */
 GList *
 soup_websocket_connection_get_extensions (SoupWebsocketConnection *self)
@@ -1882,7 +1859,6 @@ soup_websocket_connection_get_extensions (SoupWebsocketConnection *self)
  * Get the current state of the WebSocket.
  *
  * Returns: the state
- *
  */
 SoupWebsocketState
 soup_websocket_connection_get_state (SoupWebsocketConnection *self)
@@ -1907,11 +1883,10 @@ soup_websocket_connection_get_state (SoupWebsocketConnection *self)
  *
  * This only becomes valid once the WebSocket is in the
  * %SOUP_WEBSOCKET_STATE_CLOSED state. The value will often be in the
- * #SoupWebsocketCloseCode enumeration, but may also be an application
+ * [enum@WebsocketCloseCode] enumeration, but may also be an application
  * defined close code.
  *
  * Returns: the close code or zero.
- *
  */
 gushort
 soup_websocket_connection_get_close_code (SoupWebsocketConnection *self)
@@ -1934,7 +1909,6 @@ soup_websocket_connection_get_close_code (SoupWebsocketConnection *self)
  * the main loop is run, so copy it if you need to keep it around.
  *
  * Returns: the close data or %NULL
- *
  */
 const char *
 soup_websocket_connection_get_close_data (SoupWebsocketConnection *self)
@@ -1951,13 +1925,13 @@ soup_websocket_connection_get_close_data (SoupWebsocketConnection *self)
  * @self: the WebSocket
  * @text: the message contents
  *
- * Send a %NULL-terminated text (UTF-8) message to the peer. If you need
- * to send text messages containing %NULL characters use
- * soup_websocket_connection_send_message() instead.
+ * Send a %NULL-terminated text (UTF-8) message to the peer.
+ *
+ * If you need to send text messages containing %NULL characters use
+ * [method@WebsocketConnection.send_message] instead.
  *
  * The message is queued to be sent and will be sent when the main loop
  * is run.
- *
  */
 void
 soup_websocket_connection_send_text (SoupWebsocketConnection *self,
@@ -1981,11 +1955,12 @@ soup_websocket_connection_send_text (SoupWebsocketConnection *self,
  * @data: (array length=length) (element-type guint8) (nullable): the message contents
  * @length: the length of @data
  *
- * Send a binary message to the peer. If @length is 0, @data may be %NULL.
+ * Send a binary message to the peer.
+ *
+ * If @length is 0, @data may be %NULL.
  *
  * The message is queued to be sent and will be sent when the main loop
  * is run.
- *
  */
 void
 soup_websocket_connection_send_binary (SoupWebsocketConnection *self,
@@ -2010,7 +1985,6 @@ soup_websocket_connection_send_binary (SoupWebsocketConnection *self,
  *
  * The message is queued to be sent and will be sent when the main loop
  * is run.
- *
  */
 void
 soup_websocket_connection_send_message (SoupWebsocketConnection *self,
@@ -2038,7 +2012,7 @@ soup_websocket_connection_send_message (SoupWebsocketConnection *self,
  *
  * Close the connection in an orderly fashion.
  *
- * Note that until the #SoupWebsocketConnection::closed signal fires, the connection
+ * Note that until the [signal@WebsocketConnection::closed] signal fires, the connection
  * is not yet completely closed. The close message is not even sent until the
  * main loop runs.
  *
@@ -2046,7 +2020,6 @@ soup_websocket_connection_send_message (SoupWebsocketConnection *self,
  * If @code is %SOUP_WEBSOCKET_CLOSE_NO_STATUS a close message with no body
  * (without code and data) is sent.
  * Note that the @data must be UTF-8 valid.
- *
  */
 void
 soup_websocket_connection_close (SoupWebsocketConnection *self,
@@ -2076,7 +2049,6 @@ soup_websocket_connection_close (SoupWebsocketConnection *self,
  * Gets the maximum payload size allowed for incoming packets.
  *
  * Returns: the maximum payload size.
- *
  */
 guint64
 soup_websocket_connection_get_max_incoming_payload_size (SoupWebsocketConnection *self)
@@ -2093,9 +2065,9 @@ soup_websocket_connection_get_max_incoming_payload_size (SoupWebsocketConnection
  * @self: the WebSocket
  * @max_incoming_payload_size: the maximum payload size
  *
- * Sets the maximum payload size allowed for incoming packets. It
- * does not limit the outgoing packet size.
+ * Sets the maximum payload size allowed for incoming packets.
  *
+ * It does not limit the outgoing packet size.
  */
 void
 soup_websocket_connection_set_max_incoming_payload_size (SoupWebsocketConnection *self,
@@ -2118,7 +2090,6 @@ soup_websocket_connection_set_max_incoming_payload_size (SoupWebsocketConnection
  * Gets the keepalive interval in seconds or 0 if disabled.
  *
  * Returns: the keepalive interval.
- *
  */
 guint
 soup_websocket_connection_get_keepalive_interval (SoupWebsocketConnection *self)
@@ -2150,8 +2121,9 @@ on_queue_ping (gpointer user_data)
  * @interval: the interval to send a ping message or 0 to disable it
  *
  * Sets the interval in seconds on when to send a ping message which will serve
- * as a keepalive message. If set to 0 the keepalive message is disabled.
+ * as a keepalive message.
  *
+ * If set to 0 the keepalive message is disabled.
  */
 void
 soup_websocket_connection_set_keepalive_interval (SoupWebsocketConnection *self,
diff --git a/libsoup/websocket/soup-websocket-extension-deflate.c b/libsoup/websocket/soup-websocket-extension-deflate.c
index c013892b..fa98a2e2 100644
--- a/libsoup/websocket/soup-websocket-extension-deflate.c
+++ b/libsoup/websocket/soup-websocket-extension-deflate.c
@@ -69,19 +69,11 @@ typedef struct {
 /**
  * SoupWebsocketExtensionDeflate:
  *
- * A SoupWebsocketExtensionDeflate is a #SoupWebsocketExtension
+ * A SoupWebsocketExtensionDeflate is a [class@WebsocketExtension]
  * implementing permessage-deflate (RFC 7692).
  *
- * This extension is used by default in a #SoupSession when #SoupWebsocketExtensionManager
- * feature is present, and always used by #SoupServer.
- *
- */
-
-/**
- * SOUP_TYPE_WEBSOCKET_EXTENSION_DEFLATE:
- *
- * A #GType corresponding to permessage-deflate WebSocket extension.
- *
+ * This extension is used by default in a [class@Session] when [class@WebsocketExtensionManager]
+ * feature is present, and always used by [class@Server].
  */
 
 G_DEFINE_FINAL_TYPE_WITH_PRIVATE (SoupWebsocketExtensionDeflate, soup_websocket_extension_deflate, SOUP_TYPE_WEBSOCKET_EXTENSION)
diff --git a/libsoup/websocket/soup-websocket-extension-manager.c b/libsoup/websocket/soup-websocket-extension-manager.c
index 77b07cc2..23776c95 100644
--- a/libsoup/websocket/soup-websocket-extension-manager.c
+++ b/libsoup/websocket/soup-websocket-extension-manager.c
@@ -35,24 +35,22 @@
 /**
  * SoupWebsocketExtensionManager:
  *
- * SoupWebsocketExtensionManager is the #SoupSessionFeature that handles WebSockets
- * extensions for a #SoupSession.
+ * SoupWebsocketExtensionManager is the [iface@SessionFeature] that handles WebSockets
+ * extensions for a [class@Session].
  *
- * A SoupWebsocketExtensionManager is added to the session by default, and normally
+ * A #SoupWebsocketExtensionManager is added to the session by default, and normally
  * you don't need to worry about it at all. However, if you want to
  * disable WebSocket extensions, you can remove the feature from the
- * session with soup_session_remove_feature_by_type(), or disable it on
- * individual requests with soup_message_disable_feature().
- *
+ * session with [method@Session.remove_feature_by_type] or disable it on
+ * individual requests with [method@Message.disable_feature].
  **/
 
 /**
  * SOUP_TYPE_WEBSOCKET_EXTENSION_MANAGER:
  *
- * The #GType of #SoupWebsocketExtensionManager; you can use this with
- * soup_session_remove_feature_by_type() or
- * soup_message_disable_feature().
- *
+ * The #GType of [class@WebsocketExtensionManager]; you can use this with
+ * [method@Session.remove_feature_by_type] or
+ * [method@Message.disable_feature].
  */
 
 static void soup_websocket_extension_manager_session_feature_init (SoupSessionFeatureInterface *feature_interface, gpointer interface_data);
diff --git a/libsoup/websocket/soup-websocket-extension.c b/libsoup/websocket/soup-websocket-extension.c
index 6494ac5c..0ae8b5f0 100644
--- a/libsoup/websocket/soup-websocket-extension.c
+++ b/libsoup/websocket/soup-websocket-extension.c
@@ -27,18 +27,11 @@
 #include "soup-websocket-extension.h"
 
 /**
- * SECTION:soup-websocket-extension
- * @short_description: a WebSocket extension
- * @see_also: #SoupSession, #SoupWebsocketExtensionManager
- *
- * SoupWebsocketExtension is the base class for WebSocket extension objects.
- *
- */
-
-/**
  * SoupWebsocketExtension:
  *
- * Class for impelementing websocket extensions.
+ * A WebSocket extension
+ *
+ * #SoupWebsocketExtension is the base class for WebSocket extension objects.
  */
 
 /**
@@ -55,8 +48,7 @@
  * @process_incoming_message: called to process the payload data of a message
  *    after it's received. Reserved bits of the header should be cleared.
  *
- * The class structure for the SoupWebsocketExtension.
- *
+ * The class structure for the #SoupWebsocketExtension.
  */
 
 G_DEFINE_ABSTRACT_TYPE (SoupWebsocketExtension, soup_websocket_extension, G_TYPE_OBJECT)
@@ -75,10 +67,10 @@ soup_websocket_extension_class_init (SoupWebsocketExtensionClass *auth_class)
  * soup_websocket_extension_configure:
  * @extension: a #SoupWebsocketExtension
  * @connection_type: either %SOUP_WEBSOCKET_CONNECTION_CLIENT or %SOUP_WEBSOCKET_CONNECTION_SERVER
- * @params: (nullable): the parameters, or %NULL
+ * @params: (nullable): the parameters
  * @error: return location for a #GError
  *
- * Configures @extension with the given @params
+ * Configures @extension with the given @params.
  *
  * Returns: %TRUE if extension could be configured with the given parameters, or %FALSE otherwise
  */
@@ -105,11 +97,12 @@ soup_websocket_extension_configure (SoupWebsocketExtension     *extension,
  * soup_websocket_extension_get_request_params:
  * @extension: a #SoupWebsocketExtension
  *
- * Get the parameters strings to be included in the request header. If the extension
- * doesn't include any parameter in the request, this function returns %NULL.
+ * Get the parameters strings to be included in the request header.
  *
- * Returns: (nullable) (transfer full): a new allocated string with the parameters
+ * If the extension doesn't include any parameter in the request, this function
+ * returns %NULL.
  *
+ * Returns: (nullable) (transfer full): a new allocated string with the parameters
  */
 char *
 soup_websocket_extension_get_request_params (SoupWebsocketExtension *extension)
@@ -129,11 +122,12 @@ soup_websocket_extension_get_request_params (SoupWebsocketExtension *extension)
  * soup_websocket_extension_get_response_params:
  * @extension: a #SoupWebsocketExtension
  *
- * Get the parameters strings to be included in the response header. If the extension
- * doesn't include any parameter in the response, this function returns %NULL.
+ * Get the parameters strings to be included in the response header.
  *
- * Returns: (nullable) (transfer full): a new allocated string with the parameters
+ * If the extension doesn't include any parameter in the response, this function
+ * returns %NULL.
  *
+ * Returns: (nullable) (transfer full): a new allocated string with the parameters
  */
 char *
 soup_websocket_extension_get_response_params (SoupWebsocketExtension *extension)
@@ -156,14 +150,15 @@ soup_websocket_extension_get_response_params (SoupWebsocketExtension *extension)
  * @payload: (transfer full): the payload data
  * @error: return location for a #GError
  *
- * Process a message before it's sent. If the payload isn't changed the given
- * @payload is just returned, otherwise g_bytes_unref() is called on the given
- * @payload and a new #GBytes is returned with the new data.
+ * Process a message before it's sent.
+ *
+ * If the payload isn't changed the given @payload is just returned, otherwise
+ * [method@Glib.Bytes.unref] is called on the given @payload and a new
+ * [struct@GLib.Bytes] is returned with the new data.
  *
  * Extensions using reserved bits of the header will change them in @header.
  *
  * Returns: (transfer full): the message payload data, or %NULL in case of error
- *
  */
 GBytes *
 soup_websocket_extension_process_outgoing_message (SoupWebsocketExtension *extension,
@@ -192,14 +187,15 @@ soup_websocket_extension_process_outgoing_message (SoupWebsocketExtension *exten
  * @payload: (transfer full): the payload data
  * @error: return location for a #GError
  *
- * Process a message after it's received. If the payload isn't changed the given
- * @payload is just returned, otherwise g_bytes_unref() is called on the given
- * @payload and a new #GBytes is returned with the new data.
+ * Process a message after it's received.
+ *
+ * If the payload isn't changed the given @payload is just returned, otherwise
+ * [method@GLib.Bytes.unref] is called on the given @payload and a new
+ * [struct@GLib.Bytes] is returned with the new data.
  *
  * Extensions using reserved bits of the header will reset them in @header.
  *
  * Returns: (transfer full): the message payload data, or %NULL in case of error
- *
  */
 GBytes *
 soup_websocket_extension_process_incoming_message (SoupWebsocketExtension *extension,
diff --git a/libsoup/websocket/soup-websocket.c b/libsoup/websocket/soup-websocket.c
index bdcbd7c7..f0829d4e 100644
--- a/libsoup/websocket/soup-websocket.c
+++ b/libsoup/websocket/soup-websocket.c
@@ -34,42 +34,37 @@
 #define FIXED_DIGEST_LEN 20
 
 /**
- * SECTION:soup-websocket
- * @section_id: SoupWebsocket
- * @short_description: The WebSocket Protocol
- * @see_also: soup_session_websocket_connect_async(),
- *   soup_server_add_websocket_handler()
+ * SoupWebsocketConnection:
  *
- * #SoupWebsocketConnection provides support for the <ulink
- * url="http://tools.ietf.org/html/rfc6455">WebSocket</ulink> protocol.
+ * The WebSocket Protocol
  *
- * To connect to a WebSocket server, create a #SoupSession and call
- * soup_session_websocket_connect_async(). To accept WebSocket
- * connections, create a #SoupServer and add a handler to it with
- * soup_server_add_websocket_handler().
+ * Provides support for the [WebSocket](http://tools.ietf.org/html/rfc6455)
+ * protocol.
  *
- * (Lower-level support is available via
- * soup_websocket_client_prepare_handshake() and
- * soup_websocket_client_verify_handshake(), for handling the client
- * side of the WebSocket handshake, and
- * soup_websocket_server_process_handshake() for handling the server
- * side.)
- *
- * #SoupWebsocketConnection handles the details of WebSocket
- * communication. You can use soup_websocket_connection_send_text()
- * and soup_websocket_connection_send_binary() to send data, and the
- * #SoupWebsocketConnection::message signal to receive data.
- * (#SoupWebsocketConnection currently only supports asynchronous
- * I/O.)
+ * To connect to a WebSocket server, create a [class@Session] and call
+ * [method@Session.websocket_connect_async]. To accept WebSocket
+ * connections, create a [class@Server] and add a handler to it with
+ * [method@Server.add_websocket_handler].
  *
+ * (Lower-level support is available via
+ * [func@websocket_client_prepare_handshake] and
+ * [func@websocket_client_verify_handshake], for handling the client side of the
+ * WebSocket handshake, and [func@websocket_server_process_handshake] for
+ * handling the server side.)
+ *
+ * #SoupWebsocketConnection handles the details of WebSocket communication. You
+ * can use [method@WebsocketConnection.send_text] and
+ * [method@WebsocketConnection.send_binary] to send data, and the
+ * [signal@WebsocketConnection::message] signal to receive data.
+ * (#SoupWebsocketConnection currently only supports asynchronous I/O.)
  */
 
 /**
  * SOUP_WEBSOCKET_ERROR:
  *
- * A #GError domain for WebSocket-related errors. Used with
- * #SoupWebsocketError.
+ * A [struct@GLib.Error] domain for WebSocket-related errors.
  *
+ * Used with [error@WebsocketError].
  */
 
 /**
@@ -83,7 +78,6 @@
  *   because the "Origin" header was not an allowed value.
  *
  * WebSocket-related errors.
- *
  */
 
 /**
@@ -92,8 +86,7 @@
  * @SOUP_WEBSOCKET_CONNECTION_CLIENT: a client-side connection
  * @SOUP_WEBSOCKET_CONNECTION_SERVER: a server-side connection
  *
- * The type of a #SoupWebsocketConnection.
- *
+ * The type of a [class@WebsocketConnection].
  */
 
 /**
@@ -101,9 +94,7 @@
  * @SOUP_WEBSOCKET_DATA_TEXT: UTF-8 text
  * @SOUP_WEBSOCKET_DATA_BINARY: binary data
  *
- * The type of data contained in a #SoupWebsocketConnection::message
- * signal.
- *
+ * The type of data contained in a [signal@WebsocketConnection::message] signal.
  */
 
 /**
@@ -132,10 +123,10 @@
  *   the TLS handshake failed; must not be sent.
  *
  * Pre-defined close codes that can be passed to
- * soup_websocket_connection_close() or received from
- * soup_websocket_connection_get_close_code(). (However, other codes
- * are also allowed.)
+ * [method@WebsocketConnection.close] or received from
+ * [method@WebsocketConnection.get_close_code].
  *
+ * However, other codes are also allowed.
  */
 
 /**
@@ -146,7 +137,6 @@
  * @SOUP_WEBSOCKET_STATE_CLOSED: the connection is completely closed down
  *
  * The state of the WebSocket connection.
- *
  */
 
 G_DEFINE_QUARK (soup-websocket-error-quark, soup_websocket_error)
@@ -248,12 +238,13 @@ choose_subprotocol (SoupServerMessage *msg,
  *
  * Adds the necessary headers to @msg to request a WebSocket
  * handshake including supported WebSocket extensions.
+ *
  * The message body and non-WebSocket-related headers are
  * not modified.
  *
  * This is a low-level function; if you use
- * soup_session_websocket_connect_async() to create a WebSocket
- * connection, it will call this for you.
+ * [method@Session.websocket_connect_async] to create a WebSocket connection, it
+ * will call this for you.
  */
 void
 soup_websocket_client_prepare_handshake (SoupMessage *msg,
@@ -545,9 +536,9 @@ process_extensions (const char  *extensions,
  * only requests containing valid supported extensions in
  * "Sec-WebSocket-Extensions" header will be accepted.
  *
- * Normally soup_websocket_server_process_handshake()
+ * Normally [func@websocket_server_process_handshake]
  * will take care of this for you, and if you use
- * soup_server_add_websocket_handler() to handle accepting WebSocket
+ * [method@Server.add_websocket_handler] to handle accepting WebSocket
  * connections, it will call that for you. However, this function may
  * be useful if you need to perform more complicated validation; eg,
  * accepting multiple different Origins, or handling different protocols
@@ -687,7 +678,7 @@ respond_handshake_bad (SoupServerMessage *msg,
  * will be returned in @accepted_extensions parameter if non-%NULL.
  *
  * This is a low-level function; if you use
- * soup_server_add_websocket_handler() to handle accepting WebSocket
+ * [method@Server.add_websocket_handler] to handle accepting WebSocket
  * connections, it will call this for you.
  *
  * Returns: %TRUE if @msg contained a valid WebSocket handshake
@@ -802,7 +793,7 @@ soup_websocket_server_process_handshake (SoupServerMessage *msg,
  * extensions are returned in @accepted_extensions parameter if non-%NULL.
  *
  * This is a low-level function; if you use
- * soup_session_websocket_connect_async() to create a WebSocket
+ * [method@Session.websocket_connect_async] to create a WebSocket
  * connection, it will call this for you.
  *
  * Returns: %TRUE if @msg contains a completed valid WebSocket