[gupnp/wip/gi-docgen: 14/14] wip




commit 7082e75d81d77d1f98599b48d09b1f2c9a8f2e2d
Author: Jens Georg <mail jensge org>
Date:   Sat Sep 18 18:32:39 2021 +0200

    wip

 libgupnp/gupnp-context-manager.c  |  68 +++++++---
 libgupnp/gupnp-control-point.c    |  53 +++++---
 libgupnp/gupnp-device-info.c      | 270 ++++++++++++++++++--------------------
 libgupnp/gupnp-device.c           |  18 +--
 libgupnp/gupnp-resource-factory.c |   1 +
 5 files changed, 222 insertions(+), 188 deletions(-)
---
diff --git a/libgupnp/gupnp-context-manager.c b/libgupnp/gupnp-context-manager.c
index 06ab805..68bb59c 100644
--- a/libgupnp/gupnp-context-manager.c
+++ b/libgupnp/gupnp-context-manager.c
@@ -67,7 +67,7 @@ typedef struct _GUPnPContextManagerPrivate GUPnPContextManagerPrivate;
  * The final implementation depends either on the underlying operating system
  * or can configured during compile time.
  *
- * It also provides a simple filtering facility if requirted. See 
[method@GUPnP.ContextManager.get_context_filter] and
+ * It also provides a simple filtering facility if required. See 
[method@GUPnP.ContextManager.get_context_filter] and
  * [class@GUPnP.ContextFilter] for details.
  *
  * Since: 0.14.0
@@ -490,7 +490,7 @@ gupnp_context_manager_class_init (GUPnPContextManagerClass *klass)
         object_class->dispose      = gupnp_context_manager_dispose;
 
         /**
-         * GUPnPContextManager:port:
+         * GUPnPContextManager:port:(attributes org.gtk.Property.get=gupnp_context_manager_get_port)
          *
          * Port the contexts listen on, or 0 if you don't care what
          * port is used by #GUPnPContext objects created by this object.
@@ -508,7 +508,7 @@ gupnp_context_manager_class_init (GUPnPContextManagerClass *klass)
                                     G_PARAM_STATIC_NICK |
                                     G_PARAM_STATIC_BLURB));
         /**
-         * GUPnPContextManager:family:
+         * GUPnPContextManager:family:(attributes 
org.gtk.Property.get=gupnp_context_manager_get_socket_family)
          *
          * The socket family to create contexts for. Use %G_SOCKET_FAMILY_INVALID
          * for any or %G_SOCKET_FAMILY_IPV4 for IPv4 contexts or
@@ -529,7 +529,7 @@ gupnp_context_manager_class_init (GUPnPContextManagerClass *klass)
                                     G_PARAM_STATIC_STRINGS));
 
         /**
-         * GUPnPContextManager:uda-version:
+         * GUPnPContextManager:uda-version:(attributes 
org.gtk.Property.get=gupnp_context_manager_get_uda_version)
          *
          * The UDA version the contexts will support. Use %GSSDP_UDA_VERSION_UNSPECIFIED
          * for using the default UDA version.
@@ -549,7 +549,7 @@ gupnp_context_manager_class_init (GUPnPContextManagerClass *klass)
                                     G_PARAM_STATIC_STRINGS));
 
         /**
-         * GUPnPContextManager:context-filter:
+         * GUPnPContextManager:context-filter:(attributes 
org.gtk.Property.get=gupnp_context_manager_get_context_filter)
          *
          * The context filter to use.
          **/
@@ -612,7 +612,7 @@ gupnp_context_manager_class_init (GUPnPContextManagerClass *klass)
  *
  * Factory-method to create a new #GUPnPContextManager. The final type of the
  * #GUPnPContextManager depends on the compile-time selection or - in case of
- * NetworkManager - on its availability during runtime. If it is not available,
+ * NetworkManager - on its availability during run-time. If it is not available,
  * the implementation falls back to the basic Unix context manager instead.
  *
  * Equivalent to calling #gupnp_context_manager_create_full (%GSSDP_UDA_VERSION_1_0, %G_SOCKET_FAMILY_IPV4, 
port);
@@ -638,7 +638,7 @@ gupnp_context_manager_create (guint port)
  *
  * Factory-method to create a new #GUPnPContextManager. The final type of the
  * #GUPnPContextManager depends on the compile-time selection or - in case of
- * NetworkManager - on its availability during runtime. If it is not available,
+ * NetworkManager - on its availability during run-time. If it is not available,
  * the implementation falls back to the basic Unix context manager instead.
  *
  * Returns: (transfer full): A new #GUPnPContextManager object.
@@ -745,9 +745,23 @@ gupnp_context_manager_rescan_control_points (GUPnPContextManager *manager)
  *
  * By calling this function, you are asking @manager to keep a reference to
  * @control_point until its associated #GUPnPContext is no longer available.
- * You usually want to call this function from
- * #GUPnPContextManager::context-available handler after you create a
+ * You usually want to call this function from your
+ * [signal@GUPnP.ContextManager::context-available] handler after you create a
  * #GUPnPControlPoint object for the newly available context.
+ * 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.
+ *
+ * ```c
+ * void on_context_available (GUPnPContextManager *manager, GUPnPContext *context, gpointer user_data)
+ * {
+ *     GUPnPControlPoint *cp = gupnp_control_point_new (context, 
"urn:schemas-upnp-org:device:MediaRenderer:1");
+ *     gupnp_context_manager_manage_control_point (manager, cp);
+ *     // Subscribe to control point's signals etc.
+ *     g_object_unref (cp);
+ * }
+ * ```
  *
  * Since: 0.14.0
  **/
@@ -773,9 +787,25 @@ gupnp_context_manager_manage_control_point (GUPnPContextManager *manager,
  * By calling this function, you are asking @manager to keep a reference to
  * @root_device when its associated #GUPnPContext is no longer available. You
  * usually want to call this function from
- * #GUPnPContextManager::context-available handler after you create a
+ * [signal@GUPnP.ContextManager::context-available] handler after you create a
  * #GUPnPRootDevice object for the newly available context.
  *
+ * 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.
+ *
+ * ```c
+ * void on_context_available (GUPnPContextManager *manager, GUPnPContext *context, gpointer user_data)
+ * {
+ *     GError *error = NULL;
+ *
+ *     GUPnPRootDevice *rd = gupnp_root_device_new (context, "BasicLight1.xml", ".", &error);
+ *     gupnp_context_manager_manage_root_device (manager, rd);
+ *     // Subscribe to control point's signals etc.
+ *     g_object_unref (rd);
+ * }
+ * ```
  * Since: 0.14.0
  **/
 void
@@ -793,11 +823,11 @@ gupnp_context_manager_manage_root_device (GUPnPContextManager *manager,
 }
 
 /**
- * gupnp_context_manager_get_port:
+ * gupnp_context_manager_get_port:(attributes org.gtk.Method.get_property=port)
  * @manager: A #GUPnPContextManager
  *
  * Get the network port associated with this context manager.
- * Returns: The network port asssociated with this context manager.
+ * Returns: The network port associated with this context manager.
  *
  * Since: 0.20.0
  */
@@ -814,13 +844,15 @@ gupnp_context_manager_get_port (GUPnPContextManager *manager)
 }
 
 /**
- * gupnp_context_manager_get_context_filter:
+ * gupnp_context_manager_get_context_filter:(attributes org.gtk.Method.get_property=context-filter)
  * @manager: A #GUPnPContextManager
  *
  * Get the #GUPnPContextFilter associated with @manager.
  *
- * Returns: (transfer none):  The #GUPnPContextFilter asssociated with this
+ * Returns: (transfer none):  The #GUPnPContextFilter associated with this
  * context manager.
+ *
+ * Since: 1.4.0
  */
 GUPnPContextFilter *
 gupnp_context_manager_get_context_filter (GUPnPContextManager *manager)
@@ -840,9 +872,9 @@ gupnp_context_manager_get_context_filter (GUPnPContextManager *manager)
  *
  * Get the #GUPnPContextFilter associated with @manager.
  *
- * Returns: (transfer none):  The #GUPnPContextFilter asssociated with this
+ * Returns: (transfer none):  The #GUPnPContextFilter associated with this
  * context manager.
- * Deprecated: 1.4.0: Use gupnp_context_manager_get_context_filter() instead.
+ * Deprecated: 1.4.0: Use [method@GUPnP.ContextManager.get_context_filter] instead.
  */
 GUPnPWhiteList *
 gupnp_context_manager_get_white_list (GUPnPContextManager *manager)
@@ -851,7 +883,7 @@ gupnp_context_manager_get_white_list (GUPnPContextManager *manager)
 }
 
 /**
- * gupnp_context_manager_get_socket_family:
+ * gupnp_context_manager_get_socket_family:(attributes org.gtk.Method.get_property=family)
  * @manager: A #GUPnPContextManager
  *
  * Get the #GSocketFamily the contexts are created for. Can be
@@ -875,7 +907,7 @@ gupnp_context_manager_get_socket_family (GUPnPContextManager *manager)
 }
 
 /**
- * gupnp_context_manager_get_uda_version:
+ * gupnp_context_manager_get_uda_version:(attributes org.gtk.Method.get_property=uda-version)
  * @manager: A #GUPnPContextManager
  *
  * Get the UDA protocol version the contexts are implementing
diff --git a/libgupnp/gupnp-control-point.c b/libgupnp/gupnp-control-point.c
index 1e028f4..ab46561 100644
--- a/libgupnp/gupnp-control-point.c
+++ b/libgupnp/gupnp-control-point.c
@@ -10,7 +10,7 @@
 /**
  * GUPnPControlPoint:
  *
- * Class for resource discovery.
+ * Network resource discovery.
  *
  * #GUPnPControlPoint handles device and service discovery. After creating
  * a control point and activating it using [method@GSSDP.ResourceBrowser.set_active],
@@ -1027,7 +1027,7 @@ gupnp_control_point_class_init (GUPnPControlPointClass *klass)
                 gupnp_control_point_resource_unavailable;
 
         /**
-         * GUPnPControlPoint:resource-factory:
+         * GUPnPControlPoint:resource-factory:(attributes 
org.gtk.Property.get=gupnp_control_point_get_resource_factory)
          *
          * The resource factory to use. Set to NULL for default factory.
          **/
@@ -1137,8 +1137,8 @@ gupnp_control_point_class_init (GUPnPControlPointClass *klass)
  * Create a new #GUPnPControlPoint with the specified @context and @target.
  *
  * @target should be a service or device name, such as
- * <literal>urn:schemas-upnp-org:service:WANIPConnection:1</literal> or
- * <literal>urn:schemas-upnp-org:device:MediaRenderer:1</literal>.
+ * `urn:schemas-upnp-org:service:WANIPConnection:1` or
+ * `urn:schemas-upnp-org:device:MediaRenderer:1`.
  *
  * Return value: A new #GUPnPControlPoint object.
  **/
@@ -1165,8 +1165,12 @@ gupnp_control_point_new (GUPnPContext *context,
  * @target.
  *
  * @target should be a service or device name, such as
- * <literal>urn:schemas-upnp-org:service:WANIPConnection:1</literal> or
- * <literal>urn:schemas-upnp-org:device:MediaRenderer:1</literal>.
+ * `urn:schemas-upnp-org:service:WANIPConnection:1` or
+ * `urn:schemas-upnp-org:device:MediaRenderer:1`.
+ *
+ * By passing a custom `GUPnPResourceFactory`, the proxies handed out in ::device-available and
+ * ::service-available can be overridden to hand out custom classes instead of the generic
+ * [class@GUPnP.ServiceProxy] and [class@GUPnP.DeviceProxy].
  *
  * Return value: A new #GUPnPControlPoint object.
  **/
@@ -1194,6 +1198,7 @@ gupnp_control_point_new_full (GUPnPContext         *context,
  * Get the #GUPnPControlPoint associated with @control_point.
  *
  * Returns: (transfer none): The #GUPnPContext.
+ * Deprecated: 1.4.0: Use [method@GSSDP.ResourceBrowser.get_client] instead.
  **/
 GUPnPContext *
 gupnp_control_point_get_context (GUPnPControlPoint *control_point)
@@ -1212,11 +1217,17 @@ gupnp_control_point_get_context (GUPnPControlPoint *control_point)
  * gupnp_control_point_list_device_proxies:
  * @control_point: A #GUPnPControlPoint
  *
- * Get the #GList of discovered #GUPnPDeviceProxy objects. Do not free the list
- * nor its elements.
+ * Get the list of #GUPnPDeviceProxy objects the control point currently assumes to
+ * be active.
+ *
+ * Since a device might have gone offline without signalizing it, but
+ * the automatic resource timeout has not happened yet, it is possible that some of
+ * the devices listed are not available anymore on the network.
+ *
+ * Do not free the list nor its elements.
  *
- * Return value: (element-type GUPnP.DeviceProxy) (transfer none):  a #GList of
- * #GUPnPDeviceProxy objects.
+ * Return value: (element-type GUPnP.DeviceProxy) (transfer none): Device proxies
+ * currently assumed to be active.
  **/
 const GList *
 gupnp_control_point_list_device_proxies (GUPnPControlPoint *control_point)
@@ -1234,11 +1245,17 @@ gupnp_control_point_list_device_proxies (GUPnPControlPoint *control_point)
  * gupnp_control_point_list_service_proxies:
  * @control_point: A #GUPnPControlPoint
  *
- * Get the #GList of discovered #GUPnPServiceProxy objects. Do not free the
- * list nor its elements.
+ * Get the list of discovered #GUPnPServiceProxy objects the control point currently assumes to
+ * be active.
+ *
+ * Since a device might have gone offline without signalizing it, but
+ * the automatic resource timeout has not happened yet, it is possible that some of
+ * the services listed are not available anymore on the network.
+ *
+ * Do not free the list nor its elements.
  *
- * Return value: (element-type GUPnP.ServiceProxy) (transfer none): a #GList
- * of #GUPnPServiceProxy objects.
+ * Return value: (element-type GUPnP.ServiceProxy) (transfer none): Service proxies
+ * currently assumed to be active.
  **/
 const GList *
 gupnp_control_point_list_service_proxies (GUPnPControlPoint *control_point)
@@ -1253,12 +1270,14 @@ gupnp_control_point_list_service_proxies (GUPnPControlPoint *control_point)
 }
 
 /**
- * gupnp_control_point_get_resource_factory:
+ * gupnp_control_point_get_resource_factory:(attributes org.gtk.Method.get_property=resource-factory)
  * @control_point: A #GUPnPControlPoint
  *
- * Get the #GUPnPResourceFactory used by the @control_point.
+ * Get the #GUPnPResourceFactory used by the @control_point. If none was set during construction
+ * by calling [ctor@GUPnP.ControlPoint.new_full], equivalent to calling
+ * [func@GUPnP.ResourceFactory.get_default]
  *
- * Returns: (transfer none): A #GUPnPResourceFactory.
+ * Returns: (transfer none): The #GUPnPResourceFactory used by this control point
  **/
 GUPnPResourceFactory *
 gupnp_control_point_get_resource_factory (GUPnPControlPoint *control_point)
diff --git a/libgupnp/gupnp-device-info.c b/libgupnp/gupnp-device-info.c
index fd3d8ce..51e10d0 100644
--- a/libgupnp/gupnp-device-info.c
+++ b/libgupnp/gupnp-device-info.c
@@ -7,13 +7,6 @@
  *
  */
 
-/**
- * SECTION:gupnp-device-info
- * @short_description: Base abstract class for querying device information.
- *
- * The #GUPnPDeviceInfo base abstract class provides methods for querying
- * device information.
- */
 
 #include <config.h>
 #include <string.h>
@@ -39,6 +32,15 @@ struct _GUPnPDeviceInfoPrivate {
 };
 typedef struct _GUPnPDeviceInfoPrivate GUPnPDeviceInfoPrivate;
 
+/**
+ * GUPnPDeviceInfo:
+ *
+ * Base abstract class for querying device information.
+ *
+ * The #GUPnPDeviceInfo base abstract class provides methods for querying
+ * device information.
+ */
+
 G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GUPnPDeviceInfo,
                                      gupnp_device_info,
                                      G_TYPE_OBJECT)
@@ -195,113 +197,99 @@ gupnp_device_info_class_init (GUPnPDeviceInfoClass *klass)
         object_class->finalize     = gupnp_device_info_finalize;
 
         /**
-         * GUPnPDeviceInfo:resource-factory:
+         * GUPnPDeviceInfo:resource-factory:(attributes 
org.gtk.Property.get=gupnp_device_info_get_resource_factory):
          *
          * The resource factory to use. Set to NULL for default factory.
          **/
-        g_object_class_install_property
-                (object_class,
-                 PROP_RESOURCE_FACTORY,
-                 g_param_spec_object ("resource-factory",
-                                      "Resource Factory",
-                                      "The resource factory to use",
-                                      GUPNP_TYPE_RESOURCE_FACTORY,
-                                      G_PARAM_READWRITE |
-                                      G_PARAM_CONSTRUCT_ONLY |
-                                      G_PARAM_STATIC_NAME |
-                                      G_PARAM_STATIC_NICK |
-                                      G_PARAM_STATIC_BLURB));
+        g_object_class_install_property (
+                object_class,
+                PROP_RESOURCE_FACTORY,
+                g_param_spec_object ("resource-factory",
+                                     "Resource Factory",
+                                     "The resource factory to use",
+                                     GUPNP_TYPE_RESOURCE_FACTORY,
+                                     G_PARAM_READWRITE |
+                                             G_PARAM_CONSTRUCT_ONLY |
+                                             G_PARAM_STATIC_STRINGS));
 
         /**
-         * GUPnPDeviceInfo:context:
+         * GUPnPDeviceInfo:context:(attributes org.gtk.Property.get=gupnp_device_info_get_context):
          *
          * The #GUPnPContext to use.
          **/
-        g_object_class_install_property
-                (object_class,
-                 PROP_CONTEXT,
-                 g_param_spec_object ("context",
-                                      "Context",
-                                      "The GUPnPContext",
-                                      GUPNP_TYPE_CONTEXT,
-                                      G_PARAM_READWRITE |
-                                      G_PARAM_CONSTRUCT_ONLY |
-                                      G_PARAM_STATIC_NAME |
-                                      G_PARAM_STATIC_NICK |
-                                      G_PARAM_STATIC_BLURB));
+        g_object_class_install_property (
+                object_class,
+                PROP_CONTEXT,
+                g_param_spec_object ("context",
+                                     "Context",
+                                     "The GUPnPContext",
+                                     GUPNP_TYPE_CONTEXT,
+                                     G_PARAM_READWRITE |
+                                             G_PARAM_CONSTRUCT_ONLY |
+                                             G_PARAM_STATIC_STRINGS));
 
         /**
-         * GUPnPDeviceInfo:location:
+         * GUPnPDeviceInfo:location:(attributes org.gtk.Property.get=gupnp_device_info_get_location):
          *
          * The location of the device description file.
          **/
-        g_object_class_install_property
-                (object_class,
-                 PROP_LOCATION,
-                 g_param_spec_string ("location",
-                                      "Location",
-                                      "The location of the device description "
-                                      "file",
-                                      NULL,
-                                      G_PARAM_READWRITE |
-                                      G_PARAM_CONSTRUCT |
-                                      G_PARAM_STATIC_NAME |
-                                      G_PARAM_STATIC_NICK |
-                                      G_PARAM_STATIC_BLURB));
+        g_object_class_install_property (
+                object_class,
+                PROP_LOCATION,
+                g_param_spec_string ("location",
+                                     "Location",
+                                     "The location of the device description "
+                                     "file",
+                                     NULL,
+                                     G_PARAM_READWRITE | G_PARAM_CONSTRUCT |
+                                             G_PARAM_STATIC_STRINGS));
 
         /**
-         * GUPnPDeviceInfo:udn:
+         * GUPnPDeviceInfo:udn:(attributes org.gtk.Property.get=gupnp_device_info_get_udn):
          *
          * The UDN of this device.
          **/
-        g_object_class_install_property
-                (object_class,
-                 PROP_UDN,
-                 g_param_spec_string ("udn",
-                                      "UDN",
-                                      "The UDN",
-                                      NULL,
-                                      G_PARAM_READWRITE |
-                                      G_PARAM_CONSTRUCT_ONLY |
-                                      G_PARAM_STATIC_NAME |
-                                      G_PARAM_STATIC_NICK |
-                                      G_PARAM_STATIC_BLURB));
+        g_object_class_install_property (
+                object_class,
+                PROP_UDN,
+                g_param_spec_string ("udn",
+                                     "UDN",
+                                     "The Unique Device Name",
+                                     NULL,
+                                     G_PARAM_READWRITE |
+                                             G_PARAM_CONSTRUCT_ONLY |
+                                             G_PARAM_STATIC_STRINGS));
 
         /**
-         * GUPnPDeviceInfo:device-type:
+         * GUPnPDeviceInfo:device-type:(attributes org.gtk.Property.get=gupnp_device_info_get_device_type):
          *
-         * The device type.
+         * The device type, e.g. `urn:schemas-upnp-org:device:InternetGatewayDevice:1`
          **/
-        g_object_class_install_property
-                (object_class,
-                 PROP_DEVICE_TYPE,
-                 g_param_spec_string ("device-type",
-                                      "Device type",
-                                      "The device type",
-                                      NULL,
-                                      G_PARAM_READWRITE |
-                                      G_PARAM_CONSTRUCT_ONLY |
-                                      G_PARAM_STATIC_NAME |
-                                      G_PARAM_STATIC_NICK |
-                                      G_PARAM_STATIC_BLURB));
+        g_object_class_install_property (
+                object_class,
+                PROP_DEVICE_TYPE,
+                g_param_spec_string ("device-type",
+                                     "Device type",
+                                     "The device type",
+                                     NULL,
+                                     G_PARAM_READWRITE |
+                                             G_PARAM_CONSTRUCT_ONLY |
+                                             G_PARAM_STATIC_STRINGS));
 
         /**
-         * GUPnPDeviceInfo:url-base:
+         * GUPnPDeviceInfo:url-base:(attributes org.gtk.Property.get=gupnp_device_info_get_url_base):
          *
          * The URL base (#SoupURI).
          **/
-        g_object_class_install_property
-                (object_class,
-                 PROP_URL_BASE,
-                 g_param_spec_boxed ("url-base",
-                                     "URL base",
-                                     "The URL base",
-                                     SOUP_TYPE_URI,
-                                     G_PARAM_READWRITE |
-                                     G_PARAM_CONSTRUCT |
-                                     G_PARAM_STATIC_NAME |
-                                     G_PARAM_STATIC_NICK |
-                                     G_PARAM_STATIC_BLURB));
+        g_object_class_install_property (
+                object_class,
+                PROP_URL_BASE,
+                g_param_spec_boxed ("url-base",
+                                    "URL base",
+                                    "The URL base",
+                                    SOUP_TYPE_URI,
+                                    G_PARAM_READWRITE | G_PARAM_CONSTRUCT |
+                                            G_PARAM_STATIC_STRINGS));
 
         /**
          * GUPnPDeviceInfo:document:
@@ -310,19 +298,17 @@ gupnp_device_info_class_init (GUPnPDeviceInfoClass *klass)
          *
          * Stability: Private
          **/
-        g_object_class_install_property
-                (object_class,
-                 PROP_DOCUMENT,
-                 g_param_spec_object ("document",
-                                      "Document",
-                                      "The XML document related to this "
-                                      "device",
-                                      GUPNP_TYPE_XML_DOC,
-                                      G_PARAM_READWRITE |
-                                      G_PARAM_CONSTRUCT_ONLY |
-                                      G_PARAM_STATIC_NAME |
-                                      G_PARAM_STATIC_NICK |
-                                      G_PARAM_STATIC_BLURB));
+        g_object_class_install_property (
+                object_class,
+                PROP_DOCUMENT,
+                g_param_spec_object ("document",
+                                     "Document",
+                                     "The XML document related to this "
+                                     "device",
+                                     GUPNP_TYPE_XML_DOC,
+                                     G_PARAM_READWRITE |
+                                             G_PARAM_CONSTRUCT_ONLY |
+                                             G_PARAM_STATIC_STRINGS));
 
         /**
          * GUPnPDeviceInfo:element:
@@ -331,22 +317,19 @@ gupnp_device_info_class_init (GUPnPDeviceInfoClass *klass)
          *
          * Stability: Private
          **/
-        g_object_class_install_property
-                (object_class,
-                 PROP_ELEMENT,
-                 g_param_spec_pointer ("element",
-                                       "Element",
-                                       "The XML element related to this "
-                                       "device",
-                                       G_PARAM_WRITABLE |
-                                       G_PARAM_CONSTRUCT |
-                                       G_PARAM_STATIC_NAME |
-                                       G_PARAM_STATIC_NICK |
-                                       G_PARAM_STATIC_BLURB));
+        g_object_class_install_property (
+                object_class,
+                PROP_ELEMENT,
+                g_param_spec_pointer ("element",
+                                      "Element",
+                                      "The XML element related to this "
+                                      "device",
+                                      G_PARAM_WRITABLE | G_PARAM_CONSTRUCT |
+                                              G_PARAM_STATIC_STRINGS));
 }
 
 /**
- * gupnp_device_info_get_resource_factory:
+ * gupnp_device_info_get_resource_factory:(attributes org.gtk.Method.get_property=resource-factory):
  * @device_info: A #GUPnPDeviceInfo
  *
  * Get the #GUPnPResourceFactory used by the @device_info.
@@ -366,12 +349,12 @@ gupnp_device_info_get_resource_factory (GUPnPDeviceInfo *info)
 }
 
 /**
- * gupnp_device_info_get_context:
+ * gupnp_device_info_get_context:(attributes org.gtk.Method.get_property=context):
  * @info: A #GUPnPDeviceInfo
  *
  * Get the associated #GUPnPContext.
  *
- * Returns: (transfer none): A #GUPnPContext.
+ * Returns: (transfer none): The #GUPnPContext the devices is operating on.
  **/
 GUPnPContext *
 gupnp_device_info_get_context (GUPnPDeviceInfo *info)
@@ -389,9 +372,9 @@ gupnp_device_info_get_context (GUPnPDeviceInfo *info)
  * gupnp_device_info_get_location:
  * @info: A #GUPnPDeviceInfo
  *
- * Get the location of the device description file.
+ * Get the URL of the device file
  *
- * Returns: A constant string.
+ * Returns: A s
  **/
 const char *
 gupnp_device_info_get_location (GUPnPDeviceInfo *info)
@@ -406,7 +389,7 @@ gupnp_device_info_get_location (GUPnPDeviceInfo *info)
 }
 
 /**
- * gupnp_device_info_get_url_base:
+ * gupnp_device_info_get_url_base:(attributes org.gtk.Method.get_property=url-base):
  * @info: A #GUPnPDeviceInfo
  *
  * Get the URL base of this device.
@@ -426,7 +409,7 @@ gupnp_device_info_get_url_base (GUPnPDeviceInfo *info)
 }
 
 /**
- * gupnp_device_info_get_udn:
+ * gupnp_device_info_get_udn:(attributes org.gtk.Method.get_property=udn):
  * @info: A #GUPnPDeviceInfo
  *
  * Get the Unique Device Name of the device.
@@ -451,10 +434,10 @@ gupnp_device_info_get_udn (GUPnPDeviceInfo *info)
 }
 
 /**
- * gupnp_device_info_get_device_type:
+ * gupnp_device_info_get_device_type:(attributes org.gtk.Method.get_property=device-type):
  * @info: A #GUPnPDeviceInfo
  *
- * Get the UPnP device type.
+ * Get the UPnP device type of this #GUPnPDeviceInfo, e.g. 
`urn:schemas-upnp-org:device:InternetGatewayDevice:1`
  *
  * Returns: A constant string, or %NULL.
  **/
@@ -481,7 +464,8 @@ gupnp_device_info_get_device_type (GUPnPDeviceInfo *info)
  *
  * Get the friendly name of the device.
  *
- * Return value: A string, or %NULL. g_free() after use.
+ * Return value:(nullable)(transfer full):A newly allocated string containing the
+ * "friendly name" of the device, or %NULL if not available. g_free() after use.
  **/
 char *
 gupnp_device_info_get_friendly_name (GUPnPDeviceInfo *info)
@@ -502,7 +486,8 @@ gupnp_device_info_get_friendly_name (GUPnPDeviceInfo *info)
  *
  * Get the manufacturer of the device.
  *
- * Return value:(nullable)(transfer full): A string, or %NULL. g_free() after use.
+ * Return value:(nullable)(transfer full): A newly allocated string containing the
+ * manufacturer of the device, or %NULL if not available. g_free() after use.
  **/
 char *
 gupnp_device_info_get_manufacturer (GUPnPDeviceInfo *info)
@@ -671,7 +656,7 @@ gupnp_device_info_get_upc (GUPnPDeviceInfo *info)
  * @info: A #GUPnPDeviceInfo
  *
  * Get an URL pointing to the device's presentation page, for web-based
- * administration.
+ * administration, if available.
  *
  * Return value:(nullable)(transfer full): A string, or %NULL. g_free() after use.
  **/
@@ -723,12 +708,8 @@ icon_parse (xmlNode *element)
 static void
 icon_free (Icon *icon)
 {
-        if (icon->mime_type)
-                xmlFree (icon->mime_type);
-
-        if (icon->url)
-                xmlFree (icon->url);
-
+        g_clear_pointer (&icon->mime_type, xmlFree);
+        g_clear_pointer (&icon->url, xmlFree);
         g_slice_free (Icon, icon);
 }
 
@@ -753,7 +734,9 @@ icon_free (Icon *icon)
  * returned icon, or %NULL
  *
  * Get an URL pointing to the icon most closely matching the
- * given criteria, or %NULL. If @requested_mime_type is set, only icons with
+ * given criteria, or %NULL.
+ *
+ * If @requested_mime_type is set, only icons with
  * this mime type will be returned. If @requested_depth is set, only icons with
  * this or lower depth will be returned. If @requested_width and/or
  * @requested_height are set, only icons that are this size or smaller are
@@ -997,11 +980,12 @@ resource_type_match (const char *query,
  * gupnp_device_info_list_dlna_device_class_identifier:
  * @info: A #GUPnPDeviceInfo
  *
- * Get a #GList of strings that represent the device class and version as
- * announced in the device description file using the &lt;dlna:X_DLNADOC&gt;
- * element.
+ * Get a list of strings that represent the device class and version as
+ * announced in the device description file using the `<dlna:X_DLNADOC>`
+ * element, e.g. `DMS-1.51`, `M-DMS-1.51` and so on.
+ *
  * Returns:(nullable)(transfer full) (element-type utf8): a #GList of newly allocated strings or
- * %NULL if the device description doesn't contain the &lt;dlna:X_DLNADOC&gt;
+ * %NULL if the device description doesn't contain any `<dlna:X_DLNADOC>`
  * element.
  *
  * Since: 0.20.4
@@ -1107,8 +1091,8 @@ gupnp_device_info_list_dlna_capabilities (GUPnPDeviceInfo *info)
  * This function provides generic access to the contents of arbitrary elements
  * in the device description file.
  *
- * Return value:(nullable)(transfer full): a newly allocated string or %NULL if the device
- *               description doesn't contain the given @element
+ * Return value:(nullable)(transfer full): a newly allocated string containing the
+ * requested value or %NULL if the device description doesn't contain the given @element
  *
  * Since: 0.14.0
  **/
@@ -1132,8 +1116,7 @@ gupnp_device_info_get_description_value (GUPnPDeviceInfo *info,
  * @info: A #GUPnPDeviceInfo
  *
  * Get a #GList of new objects implementing #GUPnPDeviceInfo
- * representing the devices directly contained in @info. The returned list
- * should be g_list_free()'d and the elements should be g_object_unref()'d.
+ * representing the devices directly contained in @info, excluding itself.
  *
  * Note that devices are not cached internally, so that every time you
  * call this function new objects are created. The application
@@ -1141,7 +1124,7 @@ gupnp_device_info_get_description_value (GUPnPDeviceInfo *info,
  * them.
  *
  * Return value:(nullable)(element-type GUPnP.DeviceInfo) (transfer full): a #GList of
- * new #GUPnPDeviceInfo objects.
+ * new #GUPnPDeviceInfo objects or %NULL if no devices are
  **/
 GList *
 gupnp_device_info_list_devices (GUPnPDeviceInfo *info)
@@ -1229,7 +1212,7 @@ gupnp_device_info_list_device_types (GUPnPDeviceInfo *info)
  * @info: A #GUPnPDeviceInfo
  * @type: The type of the device to be retrieved.
  *
- * Get the service with type @type directly contained in @info as
+ * Get the device with type @type directly contained in @info as
  * a new object implementing #GUPnPDeviceInfo, or %NULL if no such device
  * was found. The returned object should be unreffed when done.
  *
@@ -1347,7 +1330,7 @@ gupnp_device_info_list_services (GUPnPDeviceInfo *info)
  * @info: A #GUPnPDeviceInfo
  *
  * Get a #GList of strings representing the types of the services
- * directly contained in @info.
+ * directly contained in @info, but not in its subdevices.
  *
  * Return value: (nullable)(element-type utf8) (transfer full): A #GList of strings. The
  * elements should be g_free()'d and the list should be g_list_free()'d.
@@ -1393,8 +1376,7 @@ gupnp_device_info_list_service_types (GUPnPDeviceInfo *info)
  * @type: The type of the service to be retrieved.
  *
  * Get the service with type @type directly contained in @info as a new object
- * implementing #GUPnPServiceInfo, or %NULL if no such device was found. The
- * returned object should be unreffed when done.
+ * implementing #GUPnPServiceInfo, or %NULL if no such device was found.
  *
  * Note that services are not cached internally, so that every time you call
  * this function a new object is created. The application must cache any used
diff --git a/libgupnp/gupnp-device.c b/libgupnp/gupnp-device.c
index 71b11cf..9dfef84 100644
--- a/libgupnp/gupnp-device.c
+++ b/libgupnp/gupnp-device.c
@@ -7,15 +7,6 @@
  *
  */
 
-/**
- * SECTION:gupnp-device
- * @short_description: Class for device implementations.
- *
- * #GUPnPDevice allows for retrieving a device's subdevices
- * and services. #GUPnPDevice implements the #GUPnPDeviceInfo
- * interface.
- */
-
 #include <config.h>
 #include <string.h>
 
@@ -30,6 +21,15 @@ struct _GUPnPDevicePrivate {
 };
 typedef struct _GUPnPDevicePrivate GUPnPDevicePrivate;
 
+/**
+ * GUPnPDevice:
+ *
+ * Base class for UPnP device implementations.
+ *
+ * #GUPnPDevice allows for retrieving a device's sub-devices
+ * and services. #GUPnPDevice implements the #GUPnPDeviceInfo
+ * interface.
+ */
 G_DEFINE_TYPE_WITH_PRIVATE (GUPnPDevice,
                             gupnp_device,
                             GUPNP_TYPE_DEVICE_INFO)
diff --git a/libgupnp/gupnp-resource-factory.c b/libgupnp/gupnp-resource-factory.c
index 51f121f..f73dfbb 100644
--- a/libgupnp/gupnp-resource-factory.c
+++ b/libgupnp/gupnp-resource-factory.c
@@ -11,6 +11,7 @@
 
 /**
  * GUPnPResourceFactory:
+ *
  * Associating custom Services, Devices, ServiceProxies and DeviceProxies with UPnP types.
  *
  * #GUPnPResourceFactory objects are used by [class@GUPnP.ControlPoint],


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]