[libsoup] docs: Port individual docs to gi-docgen
- From: Patrick Griffis <pgriffis src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [libsoup] docs: Port individual docs to gi-docgen
- Date: Thu, 14 Apr 2022 16:44:05 +0000 (UTC)
commit 20f63fde14b5006e3bd8969fc18432c4b6b2938a
Author: Maximiliano Sandoval R <msandova gnome org>
Date: Sat Feb 5 23:12:43 2022 +0100
docs: Port individual docs to gi-docgen
libsoup/auth/soup-auth-basic.c | 9 +-
libsoup/auth/soup-auth-digest.c | 9 +-
libsoup/auth/soup-auth-manager.c | 55 +--
libsoup/auth/soup-auth-negotiate.c | 19 +-
libsoup/auth/soup-auth-ntlm.c | 10 +-
libsoup/auth/soup-auth.c | 116 ++---
libsoup/cache/soup-cache.c | 35 +-
libsoup/content-decoder/soup-content-decoder.c | 14 +-
libsoup/content-sniffer/soup-content-sniffer.c | 31 +-
libsoup/cookies/soup-cookie-jar-db.c | 34 +-
libsoup/cookies/soup-cookie-jar-text.c | 32 +-
libsoup/cookies/soup-cookie-jar.c | 169 ++++---
libsoup/cookies/soup-cookie.c | 210 ++++-----
libsoup/hsts/soup-hsts-enforcer-db.c | 16 +-
libsoup/hsts/soup-hsts-enforcer.c | 78 ++--
libsoup/hsts/soup-hsts-enforcer.h | 2 +-
libsoup/hsts/soup-hsts-policy.c | 44 +-
libsoup/server/soup-auth-domain-basic.c | 45 +-
libsoup/server/soup-auth-domain-digest.c | 55 +--
libsoup/server/soup-auth-domain.c | 180 ++++----
libsoup/server/soup-message-body.c | 101 ++---
libsoup/server/soup-path-map.c | 4 +-
libsoup/server/soup-server-message.c | 91 ++--
libsoup/server/soup-server.c | 467 ++++++++++---------
libsoup/server/soup-socket.c | 10 +-
libsoup/soup-connection.c | 3 +-
libsoup/soup-date-utils.c | 28 +-
libsoup/soup-form.c | 117 +++--
libsoup/soup-headers.c | 117 +++--
libsoup/soup-logger.c | 131 +++---
libsoup/soup-message-headers.c | 214 +++++----
libsoup/soup-message-metrics.c | 128 +++---
libsoup/soup-message.c | 503 ++++++++++++---------
libsoup/soup-misc.c | 6 +-
libsoup/soup-multipart-input-stream.c | 77 ++--
libsoup/soup-multipart.c | 57 +--
libsoup/soup-session-feature.c | 43 +-
libsoup/soup-session.c | 451 +++++++++---------
libsoup/soup-status.c | 16 +-
libsoup/soup-tld.c | 27 +-
libsoup/soup-uri-utils.c | 24 +-
libsoup/soup-version.c | 57 +--
libsoup/websocket/soup-websocket-connection.c | 118 ++---
.../websocket/soup-websocket-extension-deflate.c | 14 +-
.../websocket/soup-websocket-extension-manager.c | 18 +-
libsoup/websocket/soup-websocket-extension.c | 52 +--
libsoup/websocket/soup-websocket.c | 75 ++-
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
@@ -17,23 +17,17 @@
#include "soup-message-private.h"
#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
@@ -46,17 +46,10 @@
#include "soup-session-private.h"
#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
@@ -16,19 +16,14 @@
#include "soup-cookie-jar-text.h"
#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
@@ -19,22 +19,14 @@
#include "soup-uri-utils-private.h"
#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
@@ -18,15 +18,6 @@
#include "soup-date-utils-private.h"
#include "soup.h"
-/**
- * SECTION:soup-hsts-policy
- * @title: SoupHSTSPolicy
- * @short_description: HSTS policies
- *
- * Policies to be used with #SoupHSTSEnforcer.
- *
- */
-
/**
* SoupHSTSPolicy:
*
@@ -34,7 +25,7 @@
* [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
@@ -14,25 +14,16 @@
#include "soup-message-body.h"
#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
@@ -26,15 +26,6 @@
#include "soup-date-utils.h"
#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
@@ -14,32 +14,20 @@
#include "soup-form.h"
#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
@@ -17,15 +17,6 @@
#include "soup-message-headers-private.h"
#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,
@@ -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 @@
* < Soup-Debug: SoupMessage 1 (0x617000)
* < Date: Sun, 12 Jan 2008 21:02:24 GMT
* < 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
@@ -15,15 +15,6 @@
#include "soup.h"
#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:
*
@@ -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
@@ -16,21 +16,14 @@
#include "soup-message-headers-private.h"
#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;
@@ -183,12 +179,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
@@ -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
@@ -12,14 +12,6 @@
#include "soup-status.h"
#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
@@ -32,15 +32,6 @@
#include "soup.h"
#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:
*
@@ -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
@@ -11,27 +11,19 @@
#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
@@ -26,19 +26,12 @@
#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
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
