[libsoup] docs: Reach 100% documentation coverage
- From: Patrick Griffis <pgriffis src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [libsoup] docs: Reach 100% documentation coverage
- Date: Tue, 3 Nov 2020 19:35:32 +0000 (UTC)
commit 730944bb1122a60443ad877dd2b29b8f5a356240
Author: Patrick Griffis <pgriffis igalia com>
Date: Tue Nov 3 13:35:14 2020 -0600
docs: Reach 100% documentation coverage
.gitlab-ci/check-docs.py | 2 +-
libsoup/auth/soup-auth-manager.c | 6 ++++++
libsoup/cache/soup-cache.c | 6 ++++++
libsoup/content-sniffer/soup-content-decoder.c | 6 ++++++
libsoup/content-sniffer/soup-content-sniffer.c | 6 ++++++
libsoup/cookies/soup-cookie-jar-db.c | 6 ++++++
libsoup/cookies/soup-cookie-jar-text.c | 8 +++++++-
libsoup/cookies/soup-cookie-jar.c | 6 ++++++
libsoup/cookies/soup-cookie.c | 2 ++
libsoup/cookies/soup-cookie.h | 2 ++
libsoup/hsts/soup-hsts-enforcer-db.c | 6 ++++++
libsoup/hsts/soup-hsts-enforcer.c | 6 ++++++
libsoup/hsts/soup-hsts-enforcer.h | 2 ++
libsoup/hsts/soup-hsts-policy.h | 5 +++++
libsoup/server/soup-auth-domain-basic.c | 6 ++++++
libsoup/server/soup-auth-domain-digest.c | 6 ++++++
libsoup/server/soup-auth-domain.c | 6 ++++++
libsoup/server/soup-message-body.c | 2 ++
libsoup/server/soup-server-message.c | 6 ++++++
libsoup/server/soup-server.c | 20 ++++++++++++++++++++
libsoup/soup-date-utils.c | 2 ++
libsoup/soup-headers.c | 2 ++
libsoup/soup-logger.c | 8 ++++++--
libsoup/soup-message.c | 25 ++++++++++++++++++++++++-
libsoup/soup-multipart-input-stream.c | 6 ++++++
libsoup/soup-multipart.c | 1 +
libsoup/soup-session.c | 6 ++++++
libsoup/soup-status.c | 1 +
libsoup/soup-uri.c | 2 +-
libsoup/soup-version.c | 2 ++
libsoup/websocket/soup-websocket-extension.c | 6 ++++++
31 files changed, 170 insertions(+), 6 deletions(-)
---
diff --git a/.gitlab-ci/check-docs.py b/.gitlab-ci/check-docs.py
index d36a64fd..8d432df7 100755
--- a/.gitlab-ci/check-docs.py
+++ b/.gitlab-ci/check-docs.py
@@ -21,4 +21,4 @@ with open('_build/docs/reference/libsoup-3.0-undocumented.txt') as f:
if undocumented_list:
print('There is missing documentation for these symbols:')
print(undocumented_list)
- # sys.exit(1)
+ sys.exit(1)
diff --git a/libsoup/auth/soup-auth-manager.c b/libsoup/auth/soup-auth-manager.c
index aca7143e..40fae627 100644
--- a/libsoup/auth/soup-auth-manager.c
+++ b/libsoup/auth/soup-auth-manager.c
@@ -35,6 +35,12 @@
* Since: 2.42
**/
+/**
+ * SoupAuthManager:
+ *
+ * Class for managing client-side HTTP authentication.
+ */
+
/**
* SOUP_TYPE_AUTH_MANAGER:
*
diff --git a/libsoup/cache/soup-cache.c b/libsoup/cache/soup-cache.c
index b0c55514..12a3f593 100644
--- a/libsoup/cache/soup-cache.c
+++ b/libsoup/cache/soup-cache.c
@@ -50,6 +50,12 @@
* #SoupCache implements a file-based cache for HTTP resources.
*/
+/**
+ * SoupCache:
+ *
+ * Class implementing caching for HTTP resources.
+ */
+
static void soup_cache_session_feature_init (SoupSessionFeatureInterface *feature_interface, gpointer
interface_data);
static SoupContentProcessorInterface *soup_cache_default_content_processor_interface;
diff --git a/libsoup/content-sniffer/soup-content-decoder.c b/libsoup/content-sniffer/soup-content-decoder.c
index 2a723b30..99a0210f 100644
--- a/libsoup/content-sniffer/soup-content-decoder.c
+++ b/libsoup/content-sniffer/soup-content-decoder.c
@@ -53,6 +53,12 @@
* Since: 2.30
**/
+/**
+ * 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 a4c6b9be..490dee6a 100644
--- a/libsoup/content-sniffer/soup-content-sniffer.c
+++ b/libsoup/content-sniffer/soup-content-sniffer.c
@@ -35,6 +35,12 @@
* Since: 2.28
**/
+/**
+ * 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;
diff --git a/libsoup/cookies/soup-cookie-jar-db.c b/libsoup/cookies/soup-cookie-jar-db.c
index ce8f390c..88a01b36 100644
--- a/libsoup/cookies/soup-cookie-jar-db.c
+++ b/libsoup/cookies/soup-cookie-jar-db.c
@@ -30,6 +30,12 @@
* renamed to avoid conflicting.)
**/
+/**
+ * SoupCookieJarDB:
+ *
+ * Subclass of #SoupCookieJar that stores cookies in a sqlite database.
+ */
+
enum {
PROP_0,
diff --git a/libsoup/cookies/soup-cookie-jar-text.c b/libsoup/cookies/soup-cookie-jar-text.c
index 2ac7660e..be39da95 100644
--- a/libsoup/cookies/soup-cookie-jar-text.c
+++ b/libsoup/cookies/soup-cookie-jar-text.c
@@ -21,9 +21,15 @@
* @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 the Mozilla "cookies.txt" format.
+ * 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.
+ */
+
enum {
PROP_0,
diff --git a/libsoup/cookies/soup-cookie-jar.c b/libsoup/cookies/soup-cookie-jar.c
index 39aa1bce..5df110c0 100644
--- a/libsoup/cookies/soup-cookie-jar.c
+++ b/libsoup/cookies/soup-cookie-jar.c
@@ -31,6 +31,12 @@
* of long-term cookie persistence.
**/
+/**
+ * SoupCookieJar:
+ *
+ * Class that stores cookies in memory.
+ */
+
enum {
CHANGED,
LAST_SIGNAL
diff --git a/libsoup/cookies/soup-cookie.c b/libsoup/cookies/soup-cookie.c
index 87d4069a..03ccc4a0 100644
--- a/libsoup/cookies/soup-cookie.c
+++ b/libsoup/cookies/soup-cookie.c
@@ -812,6 +812,8 @@ soup_cookie_set_same_site_policy (SoupCookie *cookie,
* soup_cookie_get_same_site_policy:
* @cookie: a #SoupCookie
*
+ * Returns the same-site policy for this cookie.
+ *
* Returns: a #SoupSameSitePolicy
*
* Since: 2.70
diff --git a/libsoup/cookies/soup-cookie.h b/libsoup/cookies/soup-cookie.h
index a5005344..88735ac8 100644
--- a/libsoup/cookies/soup-cookie.h
+++ b/libsoup/cookies/soup-cookie.h
@@ -15,6 +15,8 @@ G_BEGIN_DECLS
* @SOUP_SAME_SITE_POLICY_LAX: The cookie is withheld on cross-site requests but exposed on cross-site
navigations
* @SOUP_SAME_SITE_POLICY_STRICT: The cookie is only exposed for same-site requests
*
+ * Represents the same-site policies of a cookie.
+ *
* Since: 2.70
*/
typedef enum {
diff --git a/libsoup/hsts/soup-hsts-enforcer-db.c b/libsoup/hsts/soup-hsts-enforcer-db.c
index 4e5e7580..e854d286 100644
--- a/libsoup/hsts/soup-hsts-enforcer-db.c
+++ b/libsoup/hsts/soup-hsts-enforcer-db.c
@@ -26,6 +26,12 @@
* database as a backend for persistency.
**/
+/**
+ * SoupHSTSEnforcerDB:
+ *
+ * Subclass of #SoupHSTSEnforcer using an sqlite database.
+ */
+
enum {
PROP_0,
diff --git a/libsoup/hsts/soup-hsts-enforcer.c b/libsoup/hsts/soup-hsts-enforcer.c
index 25b89a50..2c47aed4 100644
--- a/libsoup/hsts/soup-hsts-enforcer.c
+++ b/libsoup/hsts/soup-hsts-enforcer.c
@@ -42,6 +42,12 @@
*
**/
+/**
+ * SoupHSTSEnforcer:
+ *
+ * Class for storing and enforcing a #SoupHSTSPolicy.
+ */
+
static void soup_hsts_enforcer_session_feature_init (SoupSessionFeatureInterface *feature_interface,
gpointer interface_data);
enum {
diff --git a/libsoup/hsts/soup-hsts-enforcer.h b/libsoup/hsts/soup-hsts-enforcer.h
index d0223188..1010a4ce 100644
--- a/libsoup/hsts/soup-hsts-enforcer.h
+++ b/libsoup/hsts/soup-hsts-enforcer.h
@@ -26,6 +26,8 @@ G_DECLARE_DERIVABLE_TYPE (SoupHSTSEnforcer, soup_hsts_enforcer, SOUP, HSTS_ENFOR
* policies.
* @changed: The class closure for the #SoupHSTSEnforcer::changed signal.
* @hsts_enforced: The class closure for the #SoupHSTSEnforcer::hsts-enforced signal.
+ *
+ * Class structure for #SoupHSTSEnforcer.
**/
struct _SoupHSTSEnforcerClass {
GObjectClass parent_class;
diff --git a/libsoup/hsts/soup-hsts-policy.h b/libsoup/hsts/soup-hsts-policy.h
index 4ddc1451..85d1f3d9 100644
--- a/libsoup/hsts/soup-hsts-policy.h
+++ b/libsoup/hsts/soup-hsts-policy.h
@@ -16,6 +16,11 @@ SOUP_AVAILABLE_IN_2_68
GType soup_hsts_policy_get_type (void);
#define SOUP_TYPE_HSTS_POLICY (soup_hsts_policy_get_type())
+/**
+ * SOUP_HSTS_POLICY_MAX_AGE_PAST:
+ *
+ * An expiration date that is always in the past.
+ */
#define SOUP_HSTS_POLICY_MAX_AGE_PAST (0)
SOUP_AVAILABLE_IN_2_68
diff --git a/libsoup/server/soup-auth-domain-basic.c b/libsoup/server/soup-auth-domain-basic.c
index 44944a26..1fa37563 100644
--- a/libsoup/server/soup-auth-domain-basic.c
+++ b/libsoup/server/soup-auth-domain-basic.c
@@ -22,6 +22,12 @@
* cleartext password) authentication.
**/
+/**
+ * SoupAuthDomainBasic:
+ *
+ * Subclass of #SoupAuthDomain for Basic authentication.
+ */
+
enum {
PROP_0,
diff --git a/libsoup/server/soup-auth-domain-digest.c b/libsoup/server/soup-auth-domain-digest.c
index da3e674c..1bce5770 100644
--- a/libsoup/server/soup-auth-domain-digest.c
+++ b/libsoup/server/soup-auth-domain-digest.c
@@ -24,6 +24,12 @@
* authentication.
**/
+/**
+ * SoupAuthDomainDigest:
+ *
+ * Subclass of #SoupAuthDomain for Digest authentication.
+ */
+
enum {
PROP_0,
diff --git a/libsoup/server/soup-auth-domain.c b/libsoup/server/soup-auth-domain.c
index 5fba8eb4..1b7da219 100644
--- a/libsoup/server/soup-auth-domain.c
+++ b/libsoup/server/soup-auth-domain.c
@@ -39,6 +39,12 @@
* those requests that don't need it.
**/
+/**
+ * SoupAuthDomain:
+ *
+ * Class managing authentication for #SoupServer.
+ */
+
enum {
PROP_0,
diff --git a/libsoup/server/soup-message-body.c b/libsoup/server/soup-message-body.c
index 87e583f3..e9925011 100644
--- a/libsoup/server/soup-message-body.c
+++ b/libsoup/server/soup-message-body.c
@@ -33,6 +33,8 @@
* @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.
+ *
+ * The lifetime of the memory being passed.
**/
/**
diff --git a/libsoup/server/soup-server-message.c b/libsoup/server/soup-server-message.c
index 1f2e8515..7406d757 100644
--- a/libsoup/server/soup-server-message.c
+++ b/libsoup/server/soup-server-message.c
@@ -34,6 +34,12 @@
* the response.
**/
+/**
+ * SoupServerMessage:
+ *
+ * Class represnting an HTTP request and response pair for a server.
+ */
+
struct _SoupServerMessage {
GObject parent;
diff --git a/libsoup/server/soup-server.c b/libsoup/server/soup-server.c
index 86357f9f..e9243ab1 100644
--- a/libsoup/server/soup-server.c
+++ b/libsoup/server/soup-server.c
@@ -120,6 +120,12 @@
* #GMainContext.
*/
+/**
+ * SoupServer:
+ *
+ * Class implementing an HTTP server.
+ */
+
enum {
REQUEST_STARTED,
REQUEST_READ,
@@ -595,6 +601,13 @@ soup_server_class_init (SoupServerClass *server_class)
*
* Since: 2.68
**/
+ /**
+ * SOUP_SERVER_ADD_WEBSOCKET_EXTENSION: (skip)
+ *
+ * Alias for %SoupServer:add-websocket-extension
+ *
+ * Since: 2.68
+ */
g_object_class_install_property (
object_class, PROP_ADD_WEBSOCKET_EXTENSION,
g_param_spec_gtype (SOUP_SERVER_ADD_WEBSOCKET_EXTENSION,
@@ -610,6 +623,13 @@ soup_server_class_init (SoupServerClass *server_class)
*
* Since: 2.68
**/
+ /**
+ * SOUP_SERVER_REMOVE_WEBSOCKET_EXTENSION: (skip)
+ *
+ * Alias for %SoupServer:remove-websocket-extension
+ *
+ * Since: 2.68
+ */
g_object_class_install_property (
object_class, PROP_REMOVE_WEBSOCKET_EXTENSION,
g_param_spec_gtype (SOUP_SERVER_REMOVE_WEBSOCKET_EXTENSION,
diff --git a/libsoup/soup-date-utils.c b/libsoup/soup-date-utils.c
index 4b904b7b..4e395044 100644
--- a/libsoup/soup-date-utils.c
+++ b/libsoup/soup-date-utils.c
@@ -29,6 +29,8 @@
* @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.
*/
/**
diff --git a/libsoup/soup-headers.c b/libsoup/soup-headers.c
index 5a54b012..c0fd1888 100644
--- a/libsoup/soup-headers.c
+++ b/libsoup/soup-headers.c
@@ -21,6 +21,8 @@
* @section_id: SoupHeaders
* @title: SoupHeaders
* @short_description: Functions to help working with HTTP Headers
+ *
+ * These are utility functions to help working with HTTP headers.
*/
/**
diff --git a/libsoup/soup-logger.c b/libsoup/soup-logger.c
index 399253a9..5a128104 100644
--- a/libsoup/soup-logger.c
+++ b/libsoup/soup-logger.c
@@ -89,12 +89,16 @@
* event of the #SoupMessage::finished signal.
**/
+/**
+ * SoupLogger:
+ *
+ * Class implementing logging.
+ */
+
struct _SoupLogger {
GObject parent;
-
};
-
typedef struct {
/* We use a mutex so that if requests are being run in
* multiple threads, we don't mix up the output.
diff --git a/libsoup/soup-message.c b/libsoup/soup-message.c
index d01a6eb6..7ed50b83 100644
--- a/libsoup/soup-message.c
+++ b/libsoup/soup-message.c
@@ -1685,6 +1685,9 @@ soup_message_set_is_top_level_navigation (SoupMessage *msg,
* soup_message_get_is_top_level_navigation:
* @msg: a #SoupMessage
*
+ * Returns if this message is set as a top level navigation.
+ * Used for same-site policy checks.
+ *
* Since: 2.70
**/
gboolean
@@ -1888,7 +1891,9 @@ soup_message_get_request_body_stream (SoupMessage *msg)
* soup_message_get_method:
* @msg: The #SoupMessage
*
- * Returns: The method of this message
+ * Returns the method of this message.
+ *
+ * Returns: A method such as %SOUP_METHOD_GET
*/
const char *
soup_message_get_method (SoupMessage *msg)
@@ -1902,6 +1907,8 @@ soup_message_get_method (SoupMessage *msg)
* soup_message_get_status:
* @msg: The #SoupMessage
*
+ * Returns the set status of this message.
+ *
* Returns: The #SoupStatus
*/
SoupStatus
@@ -1928,6 +1935,14 @@ soup_message_get_reason_phrase (SoupMessage *msg)
return priv->reason_phrase;
}
+/**
+ * soup_message_get_request_headers:
+ * @msg: The #SoupMessage
+ *
+ * Returns the headers sent with the request.
+ *
+ * Returns: The #SoupMessageHeaders
+ */
SoupMessageHeaders *
soup_message_get_request_headers (SoupMessage *msg)
{
@@ -1936,6 +1951,14 @@ soup_message_get_request_headers (SoupMessage *msg)
return priv->request_headers;
}
+/**
+ * soup_message_get_response_headers:
+ * @msg: The #SoupMessage
+ *
+ * Returns the headers recieved with the response.
+ *
+ * Returns: The #SoupMessageHeaders
+ */
SoupMessageHeaders *
soup_message_get_response_headers (SoupMessage *msg)
{
diff --git a/libsoup/soup-multipart-input-stream.c b/libsoup/soup-multipart-input-stream.c
index 59d3d77b..95097178 100644
--- a/libsoup/soup-multipart-input-stream.c
+++ b/libsoup/soup-multipart-input-stream.c
@@ -37,6 +37,12 @@
* Since: 2.40
**/
+/**
+ * SoupMultipartInputStream:
+ *
+ * Class for handling streams of multipart messages.
+ */
+
enum {
PROP_0,
diff --git a/libsoup/soup-multipart.c b/libsoup/soup-multipart.c
index b0f862bc..f2f95b31 100644
--- a/libsoup/soup-multipart.c
+++ b/libsoup/soup-multipart.c
@@ -20,6 +20,7 @@
* @short_description: multipart HTTP message bodies
* @see_also: #SoupMessageBody, #SoupMessageHeaders
*
+ * Functions to use multi-part HTTP messages.
**/
/**
diff --git a/libsoup/soup-session.c b/libsoup/soup-session.c
index 9311a095..011b4666 100644
--- a/libsoup/soup-session.c
+++ b/libsoup/soup-session.c
@@ -65,6 +65,12 @@
* subtypes) have a #SoupContentDecoder by default.
**/
+/**
+ * SoupSession:
+ *
+ * Class managing options and state for #SoupMessages.
+ */
+
typedef struct {
SoupURI *uri;
GNetworkAddress *addr;
diff --git a/libsoup/soup-status.c b/libsoup/soup-status.c
index 5eb1f635..87c6514e 100644
--- a/libsoup/soup-status.c
+++ b/libsoup/soup-status.c
@@ -17,6 +17,7 @@
* @section_id: SoupStatus
* @short_description: HTTP (and libsoup) status codes
*
+ * HTTP (and libsoup) status codes.
**/
/**
diff --git a/libsoup/soup-uri.c b/libsoup/soup-uri.c
index 2ad744be..dd27553f 100644
--- a/libsoup/soup-uri.c
+++ b/libsoup/soup-uri.c
@@ -1385,7 +1385,7 @@ soup_uri_is_https (SoupURI *uri, char **aliases)
#define BASE64_INDICATOR_LEN (sizeof (";base64") - 1)
/**
- * soup_uri_decode_data:
+ * 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
*
diff --git a/libsoup/soup-version.c b/libsoup/soup-version.c
index 0f563b59..80e9e210 100644
--- a/libsoup/soup-version.c
+++ b/libsoup/soup-version.c
@@ -15,6 +15,8 @@
* SECTION:soup-version
* @section_id: SoupVersion
* @short_description: Variables and functions to check the libsoup version
+ *
+ * Variables and functions to check the libsoup version.
**/
/**
diff --git a/libsoup/websocket/soup-websocket-extension.c b/libsoup/websocket/soup-websocket-extension.c
index 68d2bbb4..86180902 100644
--- a/libsoup/websocket/soup-websocket-extension.c
+++ b/libsoup/websocket/soup-websocket-extension.c
@@ -36,6 +36,12 @@
* Since: 2.68
*/
+/**
+ * SoupWebsocketExtension:
+ *
+ * Class for impelementing websocket extensions.
+ */
+
/**
* SoupWebsocketExtensionClass:
* @name: the name of the extension
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]