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

[Jens Georg <jensgeorg src gnome org>]

commit 3e7822f2fce001380560e43f625c1b70fc4a152d
Author: Jens Georg <mail jensge org>
Date:   Sun Aug 8 22:15:39 2021 +0200

    wip

 libgupnp/gupnp-acl.c             | 50 +++++++++++++++++++---------------------
 libgupnp/gupnp-connman-manager.c |  5 ++++
 libgupnp/gupnp-context-filter.c  | 20 ++++++++--------
 libgupnp/gupnp-context-manager.c |  1 -
 4 files changed, 39 insertions(+), 37 deletions(-)
---
diff --git a/libgupnp/gupnp-acl.c b/libgupnp/gupnp-acl.c
index b747050..1852faa 100644
--- a/libgupnp/gupnp-acl.c
+++ b/libgupnp/gupnp-acl.c
@@ -17,24 +17,12 @@
  *
  * Provide simple access control
  *
- * #GUPnPAcl provides either synchronous or asynchronous functions to check
- * whether a peer sould be able to access a resource that is hosted by GUPnP or not.
+ * 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.
  *
  * Since: 0.20.11
  */
 
-/**
- * GUPnPAclInterface:
- * @parent: The parent interface.
- * @is_allowed: Check whether access to the resource is granted.
- * @is_allowed_async: Asynchronously check whether the access is granted.
- * @is_allowed_finish: Conclude the @is_allowed_async operation.
- * @can_sync: Whether the ACL can do sync queries.
- *
- * Implement a simple access control list for GUPnP.
- *
- * Since: 0.20.11
- */
 G_DEFINE_INTERFACE(GUPnPAcl, gupnp_acl, G_TYPE_OBJECT)
 
 static void
@@ -45,9 +33,9 @@ gupnp_acl_default_init (GUPnPAclInterface *klass)
 /**
  * gupnp_acl_is_allowed:
  * @self: an instance of #GUPnPAcl
- * @device: (nullable): The #GUPnPDevice associated with @path or %NULL if
+ * @device: (nullable): The [class@GUPnP.Device] associated with @path or %NULL if
  * unknown.
- * @service: (nullable): The #GUPnPService associated with @path or %NULL if
+ * @service: (nullable): The [class@GUPnP.Service] associated with @path or %NULL if
  * unknown.
  * @path: The path being served.
  * @address: IP address of the peer.
@@ -79,26 +67,30 @@ gupnp_acl_is_allowed (GUPnPAcl     *self,
 /**
  * gupnp_acl_is_allowed_async:
  * @self: a #GUPnPAcl
- * @device: (nullable): The #GUPnPDevice associated with @path or %NULL if
+ * @device: (nullable): The [class@GUPnP.Device] associated with @path or %NULL if
  * unknown.
- * @service: (nullable): The #GUPnPService associated with @path or %NULL if
+ * @service: (nullable): The [class@GUPnP.Service] associated with @path or %NULL if
  * unknown.
  * @path: The path being served.
  * @address: IP address of the peer
  * @agent: (nullable): The User-Agent header of the peer or %NULL if not
  * unknown.
- * @cancellable: (nullable): A #GCancellable which can be used to cancel the
+ * @cancellable: (nullable): A cancellable which can be used to cancel the
  * operation.
  * @callback: Callback to call after the function is done.
  * @user_data: Some user data.
  *
- * Optional. Check asynchronously whether an IP address is allowed to access
- * this resource. Use this function if the process of verifying the access right
- * is expected to take some time, for example when using D-Bus etc.
+ * Check asynchronously whether an IP address is allowed to access
+ * this resource.
+ *
+ * This function is optional. [method GUPnP Acl.can_sync] should return %TRUE
+ * if the implementing class supports it. If it is supported, GUPnP will
+ * prefer to use this function over [method GUPnP Acl.is_allowed].
  *
- * If this function is supported, gupnp_acl_can_sync() should return %TRUE.
+ * Implement this function if the process of verifying the access right
+ * is expected to take some time, for example when using D-Bus etc.
  *
- * Use gupnp_acl_is_allowed_finish() to retrieve the result.
+ * Use [method GUPnP Acl.is_allowed_finish] to retrieve the result.
  *
 * Since: 0.20.11
  */
@@ -129,11 +121,13 @@ gupnp_acl_is_allowed_async (GUPnPAcl           *self,
 /**
  * gupnp_acl_is_allowed_finish:
  * @self: An instance of #GUPnPAcl
- * @res: %GAsyncResult obtained from the callback in gupnp_acl_is_allowed_async()
+ * @res: [class@Gio.AsyncResult] obtained from the callback passed to [method GUPnP Acl.is_allowed_async]
  * @error: (inout)(optional)(nullable): A return location for a #GError describing the failure
  * @returns %TRUE if the authentication was successful, %FALSE otherwise and on
  * error. Check @error for details.
  *
+ * Get the result of [method GUPnP Acl.is_allowed_async].
+ *
  * Since: 0.20.11
  */
 gboolean
@@ -154,7 +148,7 @@ gupnp_acl_is_allowed_finish (GUPnPAcl      *self,
  * @returns %TRUE, if gupnp_acl_is_allowed_async() is supported, %FALSE
  * otherwise.
  *
- * Check whether gupnp_acl_is_allowed_async() is supported.
+ * Check whether [method GUPnP Acl.is_allowed_async] is supported.
  *
  * Since: 0.20.11
  */
@@ -166,6 +160,10 @@ gupnp_acl_can_sync (GUPnPAcl *self)
         return GUPNP_ACL_GET_IFACE (self)->can_sync (self);
 }
 
+///////////////////////////////////////////////////////////////////
+// Internal helper functions
+//
+
 /**
  * acl_server_handler_new:
  * @service: (nullable): A #GUPnPContext or %NULL if unknown
diff --git a/libgupnp/gupnp-connman-manager.c b/libgupnp/gupnp-connman-manager.c
index f64e1b9..4dbd02c 100644
--- a/libgupnp/gupnp-connman-manager.c
+++ b/libgupnp/gupnp-connman-manager.c
@@ -54,6 +54,11 @@ struct _GUPnPConnmanManagerPrivate {
 
 typedef struct _GUPnPConnmanManagerPrivate GUPnPConnmanManagerPrivate;
 
+/**
+ * GUPnPConnmanManager:
+ *
+ * Connman-based implementation of a [class@GUPnP.ContextManager]
+ */
 struct _GUPnPConnmanManager {
         GUPnPContextManager             parent;
 };
diff --git a/libgupnp/gupnp-context-filter.c b/libgupnp/gupnp-context-filter.c
index 73cc005..ecc32a9 100644
--- a/libgupnp/gupnp-context-filter.c
+++ b/libgupnp/gupnp-context-filter.c
@@ -35,13 +35,13 @@ typedef struct _GUPnPContextFilterPrivate GUPnPContextFilterPrivate;
  *  - The network device they will live on
  *  - The name of the network the context would join
  *
- *  To add or modify a context filter, you need to retrieve the current context filter
- *  from the context manger using [method@GUPnP.ContextManager.get_context_filter].
+ * To add or modify a context filter, you need to retrieve the current context filter
+ * from the context manger using [method@GUPnP.ContextManager.get_context_filter].
  *
- *  By default, a context filter is empty and disabled.
+ * By default, a context filter is empty and disabled.
  *
- *  For example, to only react to contexts that are appearing on eth0 or when being in the WiFi network with
- *  the SSID "HomeNetwork", you should do:
+ * For example, to only react to contexts that are appearing on eth0 or when being in the WiFi network with
+ * the SSID "HomeNetwork", you should do:
  *
  *
  * ```c
@@ -161,7 +161,7 @@ gupnp_context_filter_class_init (GUPnPContextFilterClass *klass)
         object_class->finalize = gupnp_context_filter_class_finalize;
 
         /**
-         * GUPnPContextFilter:enabled:
+         * GUPnPContextFilter:enabled:(attributes org.gtk.Property.get=gupnp_context_filter_get_enabled 
org.gtk.Property.set=gupnp_context_filter_set_enabled)
          *
          * Whether this context filter is active or not.
          *
@@ -178,7 +178,7 @@ gupnp_context_filter_class_init (GUPnPContextFilterClass *klass)
                                               G_PARAM_STATIC_STRINGS));
 
         /**
-         * GUPnPContextFilter:entries: (type GList(utf8))
+         * GUPnPContextFilter:entries: (type GList(utf8))(attributes 
org.gtk.Property.get=gupnp_context_filter_get_entries)
          *
          * A list of items to filter for.
          *
@@ -189,7 +189,7 @@ gupnp_context_filter_class_init (GUPnPContextFilterClass *klass)
                 PROP_ENTRIES,
                 g_param_spec_pointer (
                         "entries",
-                        "Entries",
+                        "Filter entries",
                         "GList of strings that compose the context filter.",
                         G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE |
                                 G_PARAM_STATIC_STRINGS));
@@ -212,7 +212,7 @@ gupnp_context_filter_new (void)
 }
 
 /**
- * gupnp_context_filter_set_enabled:
+ * gupnp_context_filter_set_enabled:(attributes org.gtk.Method.set_property=enabled)
  * @context_filter: A #GUPnPContextFilter
  * @enable:  %TRUE to enable @context_filter, %FALSE otherwise
  *
@@ -234,7 +234,7 @@ gupnp_context_filter_set_enabled (GUPnPContextFilter *context_filter,
 }
 
 /**
- * gupnp_context_filter_get_enabled:
+ * gupnp_context_filter_get_enabled:(attributes org.gtk.Method.get_property=enabled)
  * @context_filter: A #GUPnPContextFilter
  *
  * Return the status of the #GUPnPContextFilter
diff --git a/libgupnp/gupnp-context-manager.c b/libgupnp/gupnp-context-manager.c
index 002ff74..06ab805 100644
--- a/libgupnp/gupnp-context-manager.c
+++ b/libgupnp/gupnp-context-manager.c
@@ -72,7 +72,6 @@ typedef struct _GUPnPContextManagerPrivate GUPnPContextManagerPrivate;
  *
  * Since: 0.14.0
  */
-
 G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GUPnPContextManager,
                                      gupnp_context_manager,
                                      G_TYPE_OBJECT)