[libgudev/bilelmoussaoui/gi-docgen: 2/6] docs: Port to gi-docgen annotations




commit 371ba0118ed46856794c617a7df8b8588833b52f
Author: Bilal Elmoussaoui <belmouss redhat com>
Date:   Sat Feb 5 13:04:32 2022 +0100

    docs: Port to gi-docgen annotations

 gudev/gudevclient.c     | 48 ++++++++++++++------------
 gudev/gudevdevice.c     | 89 +++++++++++++++++++++++++++----------------------
 gudev/gudevenumerator.c | 17 +++++-----
 3 files changed, 85 insertions(+), 69 deletions(-)
---
diff --git a/gudev/gudevclient.c b/gudev/gudevclient.c
index cfd8baa..33958ce 100644
--- a/gudev/gudevclient.c
+++ b/gudev/gudevclient.c
@@ -17,30 +17,32 @@
 #include "gudevprivate.h"
 
 /**
- * SECTION:gudevclient
- * @short_description: Query devices and listen to uevents
+ * GUdevClient:
+ * 
+ * Query devices and listen to uevents
  *
  * #GUdevClient is used to query information about devices on a Linux
  * system from the Linux kernel and the udev device
  * manager.
  *
  * Device information is retrieved from the kernel (through the
- * <literal>sysfs</literal> filesystem) and the udev daemon (through a
- * <literal>tmpfs</literal> filesystem) and presented through
- * #GUdevDevice objects. This means that no blocking IO ever happens
+ * `sysfs` filesystem) and the udev daemon (through a
+ * `tmpfs` filesystem) and presented through
+ * [class@Device] objects. This means that no blocking IO ever happens
  * (in both cases, we are essentially just reading data from kernel
  * memory) and as such there are no asynchronous versions of the
  * provided methods.
  *
- * To get #GUdevDevice objects, use
- * g_udev_client_query_by_subsystem(),
- * g_udev_client_query_by_device_number(),
- * g_udev_client_query_by_device_file(),
- * g_udev_client_query_by_sysfs_path(),
- * g_udev_client_query_by_subsystem_and_name()
- * or the #GUdevEnumerator type.
+ * To get [class@Device] objects, use
+ * 
+ * - [method@Client.query_by_subsystem]
+ * - [method@Client.query_by_device_number]
+ * - [method@Client.query_by_device_file]
+ * - [method@Client.query_by_sysfs_path]
+ * - [method@Client.query_by_subsystem_and_name]
+ * - The [class@Enumerator] type
  *
- * To listen to uevents, connect to the #GUdevClient::uevent signal.
+ * To listen to uevents, connect to the [signal@Client::uevent] signal.
  */
 
 struct _GUdevClientPrivate
@@ -309,12 +311,14 @@ g_udev_client_init (GUdevClient *client)
  * @subsystems: (array zero-terminated=1) (element-type utf8) (transfer none) (allow-none): A %NULL 
terminated string array of subsystems to listen for uevents on, %NULL to not listen on uevents at all, or an 
empty array to listen to uevents on all subsystems. See the documentation for the #GUdevClient:subsystems 
property for details on this parameter.
  *
  * Constructs a #GUdevClient object that can be used to query
- * information about devices. Connect to the #GUdevClient::uevent
- * signal to listen for uevents. Note that signals are emitted in the
+ * information about devices. 
+ * 
+ * Connect to the [signal@Client::uevent] signal to listen for uevents. 
+ * Note that signals are emitted in the
  * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
  * of the thread that you call this constructor from.
  *
- * Returns: A new #GUdevClient object. Free with g_object_unref().
+ * Returns: A new #GUdevClient object. Free with [method@GObject.Object.unref].
  */
 GUdevClient *
 g_udev_client_new (const gchar * const *subsystems)
@@ -331,8 +335,8 @@ g_udev_client_new (const gchar * const *subsystems)
  *
  * Returns: (nullable) (element-type GUdevDevice) (transfer full): A
  * list of #GUdevDevice objects. The caller should free the result by
- * using g_object_unref() on each element in the list and then
- * g_list_free() on the list.
+ * using [method@GObject.Object.unref] on each element in the list and then
+ * [func GLib List free] on the list.
  */
 GList *
 g_udev_client_query_by_subsystem (GUdevClient  *client,
@@ -386,7 +390,7 @@ g_udev_client_query_by_subsystem (GUdevClient  *client,
  * Looks up a device for a type and device number.
  *
  * Returns: (nullable) (transfer full): A #GUdevDevice object or %NULL
- * if the device was not found. Free with g_object_unref().
+ * if the device was not found. Free with [method@GObject.Object.unref].
  */
 GUdevDevice *
 g_udev_client_query_by_device_number (GUdevClient      *client,
@@ -419,7 +423,7 @@ g_udev_client_query_by_device_number (GUdevClient      *client,
  * Looks up a device for a device file.
  *
  * Returns: (nullable) (transfer full): A #GUdevDevice object or %NULL
- * if the device was not found. Free with g_object_unref().
+ * if the device was not found. Free with [method@GObject.Object.unref].
  */
 GUdevDevice *
 g_udev_client_query_by_device_file (GUdevClient  *client,
@@ -456,7 +460,7 @@ g_udev_client_query_by_device_file (GUdevClient  *client,
  * Looks up a device for a sysfs path.
  *
  * Returns: (nullable) (transfer full): A #GUdevDevice object or %NULL
- * if the device was not found. Free with g_object_unref().
+ * if the device was not found. Free with [method@GObject.Object.unref].
  */
 GUdevDevice *
 g_udev_client_query_by_sysfs_path (GUdevClient  *client,
@@ -489,7 +493,7 @@ g_udev_client_query_by_sysfs_path (GUdevClient  *client,
  * Looks up a device for a subsystem and name.
  *
  * Returns: (nullable) (transfer full): A #GUdevDevice object or %NULL
- * if the device was not found. Free with g_object_unref().
+ * if the device was not found. Free with [method@GObject.Object.unref].
  */
 GUdevDevice *
 g_udev_client_query_by_subsystem_and_name (GUdevClient  *client,
diff --git a/gudev/gudevdevice.c b/gudev/gudevdevice.c
index 38473dd..ceeeea3 100644
--- a/gudev/gudevdevice.c
+++ b/gudev/gudevdevice.c
@@ -16,45 +16,56 @@
 #include "gudevprivate.h"
 
 /**
- * SECTION:gudevdevice
- * @short_description: Get information about a device
+ * GUdevDevice:
+ * 
+ * Get information about a device
  *
  * The #GUdevDevice class is used to get information about a specific
  * device. Note that you cannot instantiate a #GUdevDevice object
- * yourself. Instead you must use #GUdevClient to obtain #GUdevDevice
+ * yourself. Instead you must use [class@Client] to obtain #GUdevDevice
  * objects.
  *
  * To get basic information about a device, use
- * g_udev_device_get_subsystem(), g_udev_device_get_devtype(),
- * g_udev_device_get_name(), g_udev_device_get_number(),
- * g_udev_device_get_sysfs_path(), g_udev_device_get_driver(),
- * g_udev_device_get_action(), g_udev_device_get_seqnum(),
- * g_udev_device_get_device_type(), g_udev_device_get_device_number(),
- * g_udev_device_get_device_file(),
- * g_udev_device_get_device_file_symlinks().
- *
- * To navigate the device tree, use g_udev_device_get_parent() and
- * g_udev_device_get_parent_with_subsystem().
+ * 
+ * - [method@Device.get_subsystem]
+ * - [method@Device.get_devtype]
+ * - [method@Device.get_name]
+ * - [method@Device.get_number]
+ * - [method@Device.get_sysfs_path]
+ * - [method@Device.get_driver]
+ * - [method@Device.get_action]
+ * - [method@Device.get_seqnum]
+ * - [method@Device.get_device_type]
+ * - [method@Device.get_device_number]
+ * - [method@Device.get_device_file]
+ * - [method@Device.get_device_file_symlinks]
+ *
+ * To navigate the device tree, use 
+ * 
+ * - [method@Device.get_parent]
+ * - [method@Device.get_parent_with_subsystem].
  *
  * To access udev properties for the device, use
- * g_udev_device_get_property_keys(),
- * g_udev_device_has_property(),
- * g_udev_device_get_property(),
- * g_udev_device_get_property_as_int(),
- * g_udev_device_get_property_as_uint64(),
- * g_udev_device_get_property_as_double(),
- * g_udev_device_get_property_as_boolean() and
- * g_udev_device_get_property_as_strv().
+ * 
+ * - [method@Device.get_property_keys]
+ * - [method@Device.has_property]
+ * - [method@Device.get_property]
+ * - [method@Device.get_property_as_int]
+ * - [method@Device.get_property_as_uint64]
+ * - [method@Device.get_property_as_double]
+ * - [method@Device.get_property_as_boolean]
+ * - [method@Device.get_property_as_strv]
  *
  * To access sysfs attributes for the device, use
- * g_udev_device_get_sysfs_attr_keys(),
- * g_udev_device_has_sysfs_attr(),
- * g_udev_device_get_sysfs_attr(),
- * g_udev_device_get_sysfs_attr_as_int(),
- * g_udev_device_get_sysfs_attr_as_uint64(),
- * g_udev_device_get_sysfs_attr_as_double(),
- * g_udev_device_get_sysfs_attr_as_boolean() and
- * g_udev_device_get_sysfs_attr_as_strv().
+ *
+ * - [method@Device.get_sysfs_attr_keys]
+ * - [method@Device.has_sysfs_attr]
+ * - [method@Device.get_sysfs_attr]
+ * - [method@Device.get_sysfs_attr_as_int]
+ * - [method@Device.get_sysfs_attr_as_uint64]
+ * - [method@Device.get_sysfs_attr_as_double]
+ * - [method@Device.get_sysfs_attr_as_boolean]
+ * - [method@Device.get_sysfs_attr_as_strv]
  *
  * Note that all getters on #GUdevDevice are non-reffing – returned
  * values are owned by the object, should not be freed and are only
@@ -63,7 +74,7 @@
  * By design, #GUdevDevice will not react to changes for a device – it
  * only contains a snapshot of information when the #GUdevDevice
  * object was created. To work with changes, you typically connect to
- * the #GUdevClient::uevent signal on a #GUdevClient and get a new
+ * the [signal@Client::uevent] signal on a [class@Client] and get a new
  * #GUdevDevice whenever an event happens.
  */
 
@@ -188,7 +199,7 @@ g_udev_device_get_name (GUdevDevice *device)
  * g_udev_device_get_number:
  * @device: A #GUdevDevice.
  *
- * Gets the number of @device, e.g. "3" if g_udev_device_get_name() returns "sda3".
+ * Gets the number of @device, e.g. "3" if [method@Device.get_name] returns "sda3".
  *
  * Returns: The number of @device.
  */
@@ -369,7 +380,7 @@ g_udev_device_get_device_file_symlinks (GUdevDevice *device)
  * Gets the immediate parent of @device, if any.
  *
  * Returns: (nullable) (transfer full): A #GUdevDevice or %NULL if
- * @device has no parent. Free with g_object_unref().
+ * @device has no parent. Free with [method@GObject.Object.unref].
  */
 GUdevDevice *
 g_udev_device_get_parent (GUdevDevice  *device)
@@ -402,7 +413,7 @@ g_udev_device_get_parent (GUdevDevice  *device)
  *
  * Returns: (nullable) (transfer full): A #GUdevDevice or %NULL if
  * @device has no parent with @subsystem and @devtype. Free with
- * g_object_unref().
+ * [method@GObject.Object.unref].
  */
 GUdevDevice *
 g_udev_device_get_parent_with_subsystem (GUdevDevice  *device,
@@ -537,7 +548,7 @@ out:
  * @key: Name of property.
  *
  * Look up the value for @key on @device and convert it to an unsigned
- * 64-bit integer using g_ascii_strtoull().
+ * 64-bit integer using [func@GLib.ascii_strtoull].
  *
  * Returns: The value  for @key or 0 if @key doesn't  exist or isn't a
  * #guint64.
@@ -568,7 +579,7 @@ out:
  * @key: Name of property.
  *
  * Look up the value for @key on @device and convert it to a double
- * precision floating point number using g_ascii_strtod().
+ * precision floating point number using [func@GLib.ascii_strtod].
  *
  * Returns: The value for @key or 0.0 if @key doesn't exist or isn't a
  * #gdouble.
@@ -823,7 +834,7 @@ out:
  * @name: Name of the sysfs attribute.
  *
  * Look up the sysfs attribute with @name on @device and convert it to an unsigned
- * 64-bit integer using g_ascii_strtoull(). The retrieved value is cached in the
+ * 64-bit integer using [func@GLib.ascii_strtoull]. The retrieved value is cached in the
  * device. Repeated calls will return the same value and not open the attribute
  * again, unless updated through one of the "uncached" functions.
  *
@@ -856,7 +867,7 @@ out:
  * @name: Name of the sysfs attribute.
  *
  * Look up the sysfs attribute with @name on @device and convert it to a double
- * precision floating point number using g_ascii_strtod(). The retrieved value is cached
+ * precision floating point number using [func@GLib.ascii_strtod]. The retrieved value is cached
  * in the device. Repeated calls will return the same value and not open the
  * attribute again, unless updated through one of the "uncached" functions.
  *
@@ -1082,7 +1093,7 @@ out:
  * @name: Name of the sysfs attribute.
  *
  * Look up the sysfs attribute with @name on @device and convert it to an unsigned
- * 64-bit integer using g_ascii_strtoull(). This function does blocking I/O, and
+ * 64-bit integer using [func@GLib.ascii_strtoull]. This function does blocking I/O, and
  * updates the sysfs attributes cache.
  *
  * Returns: The value of the sysfs attribute or 0 if there is no such
@@ -1114,7 +1125,7 @@ out:
  * @name: Name of the sysfs attribute.
  *
  * Look up the sysfs attribute with @name on @device and convert it to a double
- * precision floating point number using g_ascii_strtod(). This function does blocking
+ * precision floating point number using [func@GLib.ascii_strtod]. This function does blocking
  * I/O, and updates the sysfs attributes cache.
  *
  * Returns: The value of the sysfs attribute or 0.0 if there is no such
diff --git a/gudev/gudevenumerator.c b/gudev/gudevenumerator.c
index f908f82..127e561 100644
--- a/gudev/gudevenumerator.c
+++ b/gudev/gudevenumerator.c
@@ -17,10 +17,9 @@
 #include "gudevprivate.h"
 
 /**
- * SECTION:gudevenumerator
- * @short_description: Lookup and sort devices
- *
- * #GUdevEnumerator is used to lookup and sort devices.
+ * GUdevEnumerator:
+ * 
+ * Lookup and sort devices
  *
  * Since: 165
  */
@@ -155,11 +154,13 @@ g_udev_enumerator_init (GUdevEnumerator *enumerator)
  * @client: A #GUdevClient to enumerate devices from.
  *
  * Constructs a #GUdevEnumerator object that can be used to enumerate
- * and sort devices. Use the add_match_*() and add_nomatch_*() methods
+ * and sort devices. 
+ * 
+ * Use the add_match_*() and add_nomatch_*() methods
  * and execute the query to get a list of devices with
- * g_udev_enumerator_execute().
+ * [method@Enumerator.execute].
  *
- * Returns: A new #GUdevEnumerator object. Free with g_object_unref().
+ * Returns: A new #GUdevEnumerator object. Free with [method@GObject.Object.unref].
  *
  * Since: 165
  */
@@ -372,7 +373,7 @@ g_udev_enumerator_add_match_is_initialized (GUdevEnumerator  *enumerator)
  *
  * Executes the query in @enumerator.
  *
- * Returns: (element-type GUdevDevice) (transfer full): A list of #GUdevDevice objects. The caller should 
free the result by using g_object_unref() on each element in the list and then g_list_free() on the list.
+ * Returns: (element-type GUdevDevice) (transfer full): A list of #GUdevDevice objects. The caller should 
free the result by using [method@GObject.Object.unref] on each element in the list and then [func GLib List 
free] on the list.
  *
  * Since: 165
  */


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