GNOME.org
 

[libsoup] docs: Reach 100% documentation coverage

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]