Verified Commit 20f63fde authored by Maximiliano's avatar Maximiliano 🥑 Committed by Maximiliano
Browse files

docs: Port individual docs to gi-docgen

parent c7a4b24e
......@@ -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.
*
*/
......
......@@ -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.
*
*/
......
......@@ -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
......
......@@ -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)
......
......@@ -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)
......
......@@ -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.
**/
......
......@@ -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)
......
......@@ -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;
};
......
......@@ -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".