GNOME.org
 

[gupnp/wip/gi-docgen: 61/61] Wip


commit e40db479cd17db5e72ae0e2b1d7c02adc7ecd8c1
Author: Jens Georg <mail jensge org>
Date:   Mon Jan 3 11:05:50 2022 +0100

    Wip

 libgupnp/gupnp-acl.c                   |  2 +-
 libgupnp/gupnp-acl.h                   |  2 ++
 libgupnp/gupnp-context-manager.c       |  4 ++--
 libgupnp/gupnp-error.h                 | 24 +++++++++----------
 libgupnp/gupnp-service-introspection.c |  2 +-
 libgupnp/gupnp-service-proxy-action.c  | 32 ++++++++++++++++++++------
 libgupnp/gupnp-service-proxy.c         | 42 +++++++++++++++++++---------------
 libgupnp/gupnp-service-proxy.h         |  8 +++++++
 libgupnp/gupnp-types.h                 | 12 ++++++++++
 9 files changed, 86 insertions(+), 42 deletions(-)
---
diff --git a/libgupnp/gupnp-acl.c b/libgupnp/gupnp-acl.c
index 072045e..6a4cd1b 100644
--- a/libgupnp/gupnp-acl.c
+++ b/libgupnp/gupnp-acl.c
@@ -15,7 +15,7 @@
 /**
  * GUPnPAcl:
  *
- * Provide simple access control
+ * Access control provider for [class@GUPnP.Context]
  *
  * GUPnPAcl provides either synchronous or asynchronous functions to check
  * whether a peer should be able to access a resource that is hosted by GUPnP or not.
diff --git a/libgupnp/gupnp-acl.h b/libgupnp/gupnp-acl.h
index 1a55af4..74d8ce5 100644
--- a/libgupnp/gupnp-acl.h
+++ b/libgupnp/gupnp-acl.h
@@ -54,11 +54,13 @@ struct _GUPnPAclInterface {
 
 
     /*< private >*/
+#ifndef GOBJECT_INTROSPECTION_SKIP
     /* future padding */
     void (* _gupnp_reserved1) (void);
     void (* _gupnp_reserved2) (void);
     void (* _gupnp_reserved3) (void);
     void (* _gupnp_reserved4) (void);
+#endif
 };
 
 gboolean
diff --git a/libgupnp/gupnp-context-manager.c b/libgupnp/gupnp-context-manager.c
index 918cd50..5092005 100644
--- a/libgupnp/gupnp-context-manager.c
+++ b/libgupnp/gupnp-context-manager.c
@@ -751,7 +751,7 @@ gupnp_context_manager_rescan_control_points (GUPnPContextManager *manager)
  * You usually then give up your own reference to the control point so it will be
  * automatically destroyed if its context is no longer available.
  *
- * This function is mainly useful when implementing a UPnP client.
+ * This function is mainly useful when implementing an UPnP client.
  *
  * ```c
  * void on_context_available (GUPnPContextManager *manager, GUPnPContext *context, gpointer user_data)
@@ -793,7 +793,7 @@ gupnp_context_manager_manage_control_point (GUPnPContextManager *manager,
  * You usually then give up your own reference to the root device so it will be
  * automatically destroyed if its context is no longer available.
  *
- * This function is mainly useful when implementing a UPnP client.
+ * This function is mainly useful when implementing an UPnP client.
  *
  * ```c
  * void on_context_available (GUPnPContextManager *manager, GUPnPContext *context, gpointer user_data)
diff --git a/libgupnp/gupnp-error.h b/libgupnp/gupnp-error.h
index 2baa4ff..ad84064 100644
--- a/libgupnp/gupnp-error.h
+++ b/libgupnp/gupnp-error.h
@@ -27,8 +27,7 @@ gupnp_server_error_quark (void) G_GNUC_CONST;
  * @GUPNP_SERVER_ERROR_INVALID_URL: Invalid URL.
  * @GUPNP_SERVER_ERROR_OTHER: Unknown/unhandled error.
  *
- * #GError codes used for errors in the #GUPNP_SERVER_ERROR domain, when there
- * is communication with another server.
+ * Error codes during communication with another server.
  */
 typedef enum {
         GUPNP_SERVER_ERROR_INTERNAL_SERVER_ERROR,
@@ -50,8 +49,7 @@ gupnp_eventing_error_quark (void) G_GNUC_CONST;
  * @GUPNP_EVENTING_ERROR_SUBSCRIPTION_LOST: The subscription was lost.
  * @GUPNP_EVENTING_ERROR_NOTIFY_FAILED: The notification failed.
  *
- * #GError codes used for errors in the #GUPNP_EVENTING_ERROR domain, during
- * eventing of state variables.
+ * Error codes during eventing of state variables.
  */
 typedef enum {
         GUPNP_EVENTING_ERROR_SUBSCRIPTION_FAILED,
@@ -71,8 +69,7 @@ gupnp_control_error_quark (void) G_GNUC_CONST;
  * @GUPNP_CONTROL_ERROR_OUT_OF_SYNC: Out of sync (deprecated).
  * @GUPNP_CONTROL_ERROR_ACTION_FAILED: The action failed.
  *
- * #GError codes used for errors in the #GUPNP_CONTROL_ERROR domain, during
- * invocation of service actions.
+ * Error codes used during invocation of service actions.
  */
 typedef enum {
         GUPNP_CONTROL_ERROR_INVALID_ACTION = 401,
@@ -94,8 +91,7 @@ gupnp_xml_error_quark (void) G_GNUC_CONST;
  * @GUPNP_XML_ERROR_INVALID_ATTRIBUTE: An XML node has an unknown attribute.
  * @GUPNP_XML_ERROR_OTHER: Unknown/unhandled XML related errors.
  *
- * #GError codes used for errors in the #GUPNP_XML_ERROR domain, during
- * processing of XML data.
+ * Errors during occuring during processing of XML data.
  */
 typedef enum {
         GUPNP_XML_ERROR_PARSE,
@@ -111,13 +107,13 @@ gupnp_rootdevice_error_quark (void) G_GNUC_CONST;
 #define GUPNP_ROOT_DEVICE_ERROR (gupnp_rootdevice_error_quark ())
 
 /**
- * GUPnPRootDeviceError:
+ * GUPnPRootdeviceError:
  * @GUPNP_ROOT_DEVICE_ERROR_NO_CONTEXT: No #GUPnPContext was passed to the root device.
  * @GUPNP_ROOT_DEVICE_ERROR_NO_DESCRIPTION_PATH: Device description path was missing
  * @GUPNP_ROOT_DEVICE_ERROR_NO_DESCRIPTION_FOLDER: Description folder was missing
  * @GUPNP_ROOT_DEVICE_ERROR_NO_NETWORK: Network interface is not usable
  *
- * #GError codes used for errors during #GUPnPRootDevice creation
+ * Errors during [class@GUPnP.RootDevice] creation
  */
 typedef enum {
         GUPNP_ROOT_DEVICE_ERROR_NO_CONTEXT,
@@ -135,7 +131,9 @@ gupnp_service_introspection_error_quark (void) G_GNUC_CONST;
 
 /**
  * GUPnPServiceIntrospectionError:
- * @GUPNP_SERVICE_INTROSPECTION_ERROR_OTHER@: Unknown error
+ * @GUPNP_SERVICE_INTROSPECTION_ERROR_OTHER: Unknown error
+ *
+ * Errors during service introspection
  */
 typedef enum
 {
@@ -151,7 +149,9 @@ gupnp_service_error_quark (void) G_GNUC_CONST;
 
 /**
  * GUPnPServiceError:
- * @GUPNP_SERVICE_ERROR_AUTOCONNECT@: [method@GUPnP.Service.signals_autoconnect] failed
+ * @GUPNP_SERVICE_ERROR_AUTOCONNECT: [method@GUPnP.Service.signals_autoconnect] failed
+ *
+ * Errors during service handling
  */
 typedef enum
 {
diff --git a/libgupnp/gupnp-service-introspection.c b/libgupnp/gupnp-service-introspection.c
index 3eb471c..a56d280 100644
--- a/libgupnp/gupnp-service-introspection.c
+++ b/libgupnp/gupnp-service-introspection.c
@@ -60,7 +60,7 @@ gupnp_service_introspection_initable_iface_init (gpointer g_iface, gpointer ifac
  *
  * Note that all the introspection information is retrieved from the service
  * description document (SCPD) provided by the service and hence can not be
- * guaranteed to be complete. A UPnP service is required to provide a SCPD but
+ * guaranteed to be complete. An UPnP service is required to provide a SCPD but
  * unfortunately, many services either do not provide this document or the
  * document does not provide any or all of the introspection information.
  *
diff --git a/libgupnp/gupnp-service-proxy-action.c b/libgupnp/gupnp-service-proxy-action.c
index 15ba28c..aeb90cd 100644
--- a/libgupnp/gupnp-service-proxy-action.c
+++ b/libgupnp/gupnp-service-proxy-action.c
@@ -213,6 +213,16 @@ gupnp_service_proxy_action_new_internal (const char *action) {
         return ret;
 }
 
+
+/**
+ * gupnp_service_proxy_action_ref:
+ * @action: an action
+ *
+ * Increases reference count of `action`
+ *
+ * Returns: (nullable): @action with an increased reference count
+ * Since: 1.2.0
+ */
 GUPnPServiceProxyAction *
 gupnp_service_proxy_action_ref (GUPnPServiceProxyAction *action)
 {
@@ -246,6 +256,15 @@ action_dispose (GUPnPServiceProxyAction *action)
         g_free (action->name);
 }
 
+/**
+ * gupnp_service_proxy_action_unref:
+ * @action: an action
+ *
+ * Decreases reference count of `action`. If reference count drops to 0,
+ * the action and its contents will be freed.
+ *
+ * Since: 1.2.0
+ */
 void
 gupnp_service_proxy_action_unref (GUPnPServiceProxyAction *action)
 {
@@ -499,11 +518,11 @@ gupnp_service_proxy_action_serialize (GUPnPServiceProxyAction *action,
  * @error:(inout)(optional)(nullable): The location where to store any error, or %NULL
  *
  * A variant of gupnp_service_proxy_action_get_result() that takes lists of
- * out-parameter names, types and place-holders for values. The returned list
- * in @out_values must be freed using #g_list_free and each element in it using
- * #g_value_unset and #g_free.
- * <informalexample>
- * <programlisting>
+ * out-parameter names, types and place-holders for values.
+ *
+ * The returned list in @out_values must be freed using `g_list_free` and each element
+ * in it using `g_value_unset` and `g_free`.
+ * ```c
  * void on_action_finished(GObject *object, GAsyncResult *res, gpointer user_data)
  * {
  *     GUPnPServiceProxyAction *action;
@@ -547,8 +566,7 @@ gupnp_service_proxy_action_serialize (GUPnPServiceProxyAction *action,
  *     }
  *     g_list_free (out_values);
  * }
- * </programlisting>
- * </informalexample>
+ *```
  *
  * Return value : %TRUE on success.
  *
diff --git a/libgupnp/gupnp-service-proxy.c b/libgupnp/gupnp-service-proxy.c
index 3c65414..4fce193 100644
--- a/libgupnp/gupnp-service-proxy.c
+++ b/libgupnp/gupnp-service-proxy.c
@@ -7,15 +7,6 @@
  *
  */
 
-/**
- * SECTION:gupnp-service-proxy
- * @short_description: Proxy class for remote services.
- *
- * #GUPnPServiceProxy sends commands to a remote UPnP service and handles
- * incoming event notifications. #GUPnPServiceProxy implements the
- * #GUPnPServiceInfo interface.
- */
-
 #include <config.h>
 #include <libsoup/soup.h>
 #include <gobject/gvaluecollector.h>
@@ -53,6 +44,14 @@ struct _GUPnPServiceProxyPrivate {
 };
 typedef struct _GUPnPServiceProxyPrivate GUPnPServiceProxyPrivate;
 
+/**
+ * GUPnPServiceProxy:
+ *
+ * Proxy class for remote services.
+ *
+ * #GUPnPServiceProxy sends commands to a remote UPnP service and handles
+ * incoming event notifications.
+ */
 G_DEFINE_TYPE_WITH_PRIVATE (GUPnPServiceProxy,
                             gupnp_service_proxy,
                             GUPNP_TYPE_SERVICE_INFO)
@@ -375,10 +374,12 @@ gupnp_service_proxy_class_init (GUPnPServiceProxyClass *klass)
  * out parameter type, and out parameter value location, terminated with %NULL
  *
  * Sends action @action with parameters @Varargs to the service exposed by
- * @proxy synchronously. If an error occurred, @error will be set. In case of
- * an UPnPError the error code will be the same in @error.
+ * @proxy synchronously.
  *
- * Return value: %TRUE if sending the action was succesful.
+ * If an error occurred, @error will be set. In case of
+ * an UPnP error the error code will be the same in @error.
+ *
+ * Return value: %TRUE if sending the action was successful.
  *
  * Deprecated: 1.2.0: Use gupnp_service_proxy_action_new() and
  * gupnp_service_proxy_call_action()
@@ -415,7 +416,7 @@ gupnp_service_proxy_send_action (GUPnPServiceProxy *proxy,
  *
  * See gupnp_service_proxy_send_action().
  *
- * Return value: %TRUE if sending the action was succesful.
+ * Return value: %TRUE if sending the action was successful.
  *
  * Deprecated: 1.2.0
  **/
@@ -486,10 +487,10 @@ out:
  * (as #GValue) that line up with @out_names and @out_types.
  * @error: (inout)(optional)(nullable): The location where to store any error, or %NULL
  *
- * The synchronous variant of #gupnp_service_proxy_begin_action_list and
- * #gupnp_service_proxy_end_action_list.
+ * The synchronous variant of [class@GUPnP.ServiceProxy.begin_action_list] and
+ * [class@GUPnP.ServiceProxy.end_action_list].
  *
- * Return value: %TRUE if sending the action was succesful.
+ * Return value: %TRUE if sending the action was successful.
  *
  * Deprecated: 1.2.0: Use gupnp_service_proxy_action_new_from_list() and gupnp_service_proxy_call_action()
  *
@@ -994,7 +995,9 @@ gupnp_service_proxy_end_action_valist (GUPnPServiceProxy       *proxy,
  * (as #GValue) that line up with @out_names and @out_types.
  *
  * A variant of #gupnp_service_proxy_end_action that takes lists of
- * out-parameter names, types and place-holders for values. The returned list
+ * out-parameter names, types and place-holders for values.
+ *
+ * The returned list
  * in @out_values must be freed using #g_list_free and each element in it using
  * #g_value_unset and #g_slice_free.
  *
@@ -1212,8 +1215,9 @@ gupnp_service_proxy_add_notify_full (GUPnPServiceProxy              *proxy,
  * @user_data: User data for @callback
  * @notify: (allow-none): A #GDestroyNotify for @user_data
  *
- * Get a notification for anything that happens on the peer. @value in
- * @callback will be of type #G_TYPE_POINTER and contain the pre-parsed
+ * Get a notification for anything that happens on the peer.
+ *
+ * @value in @callback will be of type #G_TYPE_POINTER and contain the pre-parsed
  * #xmlDoc. Do NOT free or modify this document.
  *
  * Return value: %TRUE on success.
diff --git a/libgupnp/gupnp-service-proxy.h b/libgupnp/gupnp-service-proxy.h
index 107416a..7c4b8e9 100644
--- a/libgupnp/gupnp-service-proxy.h
+++ b/libgupnp/gupnp-service-proxy.h
@@ -30,14 +30,21 @@ struct _GUPnPServiceProxyClass {
         GUPnPServiceInfoClass parent_class;
 
         /* signals */
+        /**
+         * subscription_lost:
+         *
+         * Test
+         */
         void (* subscription_lost) (GUPnPServiceProxy *proxy,
                                     const GError      *reason);
 
+#ifndef GOBJECT_INTROSPECTION_SKIP
         /* future padding */
         void (* _gupnp_reserved1) (void);
         void (* _gupnp_reserved2) (void);
         void (* _gupnp_reserved3) (void);
         void (* _gupnp_reserved4) (void);
+#endif
 };
 
 /**
@@ -55,6 +62,7 @@ typedef struct _GUPnPServiceProxyAction GUPnPServiceProxyAction;
  *
  * Callback notifying that @action on @proxy has returned and
  * gupnp_service_proxy_end_action() etc can be called.
+ * Deprecated: 1.2.0
  **/
 typedef void (* GUPnPServiceProxyActionCallback) (
                                      GUPnPServiceProxy       *proxy,
diff --git a/libgupnp/gupnp-types.h b/libgupnp/gupnp-types.h
index 78f2fab..ea36c30 100644
--- a/libgupnp/gupnp-types.h
+++ b/libgupnp/gupnp-types.h
@@ -105,9 +105,21 @@ gupnp_uri_get_type (void) G_GNUC_CONST; /* string */
 GType
 gupnp_uuid_get_type (void) G_GNUC_CONST; /* string */
 
+/**
+ * gupnp_value_get_xml_node:
+ * @value: a [GLib.Value]
+ *
+ * Helper macro to get the xmlNode* from a `GValue`
+ */
 #define gupnp_value_get_xml_node( value ) \
         (xmlNode *) g_value_get_boxed ((value))
 
+/**
+ * gupnp_value_get_string:
+ * @value: a [GLib.Value]
+ *
+ * Helper macro to get a char* from a `GValue`
+ */
 #define gupnp_value_get_string( value ) \
         (const char *) g_value_get_boxed ((value))
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]