libudev: doc - add section headers

diff --git a/libudev/libudev-device.c b/libudev/libudev-device.c
index aef62567341136bdd5d92795a01cbfa2582c48d2..9965972b3288c5c1a58b5273e0d7347f86a6b822 100644 (file)
--- a/libudev/libudev-device.c
+++ b/libudev/libudev-device.c
@@ -23,10 +23,20 @@
 #include "libudev.h"
 #include "libudev-private.h"
 
+/**
+ * SECTION:libudev-device
+ * @short_description: kernel sys devices
+ *
+ * Representation of kernel sys devices. Devices are uniquely identified
+ * by their syspath, every device has exactly one path in the kernel sys
+ * filesystem. Devices usually belong to a kernel subsystem, and and have
+ * a unique name inside that subsytem.
+ */
+
 /**
  * udev_device:
  *
- * Representation of a kernel sys device.
+ * Opaque object representing one kernel sys device.
  */
 struct udev_device {
        struct udev *udev;
@@ -882,7 +892,7 @@ struct udev_list_entry *udev_device_get_properties_list_entry(struct udev_device
  * udev_device_get_driver:
  * @udev_device: udev device
  *
- * Returns: the driver string or #NULL, if ther is no driver attached.
+ * Returns: the driver string, or #NULL if there is no driver attached.
  **/
 const char *udev_device_get_driver(struct udev_device *udev_device)
 {

diff --git a/libudev/libudev-enumerate.c b/libudev/libudev-enumerate.c
index 63f84062b202a9ea21659656da487b0b636579d7..08f4af0ee785f1f40782f3366a8ba67652f8f7f4 100644 (file)
--- a/libudev/libudev-enumerate.c
+++ b/libudev/libudev-enumerate.c
@@ -24,6 +24,19 @@
 
 static int devices_sort(struct udev_enumerate *udev_enumerate);
 
+/**
+ * SECTION:libudev-enumerate
+ * @short_description: lookup and sort sys devices
+ *
+ * Lookup devices in the sys filesystem, filter devices by properties,
+ * and return a sorted list of matching devices.
+ */
+
+/**
+ * udev_enumerate:
+ *
+ * Opaque object representing one device lookup/sort context.
+ */
 struct udev_enumerate {
        struct udev *udev;
        int refcount;
@@ -60,6 +73,14 @@ struct udev_enumerate *udev_enumerate_new(struct udev *udev)
        return udev_enumerate;
 }
 
+/**
+ * udev_enumerate_ref:
+ * @udev_enumerate: context
+ *
+ * Take a reference of a enumeration context.
+ *
+ * Returns: the passed enumeration context
+ **/
 struct udev_enumerate *udev_enumerate_ref(struct udev_enumerate *udev_enumerate)
 {
        if (udev_enumerate == NULL)
@@ -68,6 +89,14 @@ struct udev_enumerate *udev_enumerate_ref(struct udev_enumerate *udev_enumerate)
        return udev_enumerate;
 }
 
+/**
+ * udev_enumerate_unref:
+ * @udev_enumerate: context
+ *
+ * Drop a reference of an enumeration context. If the refcount reaches zero,
+ * all resources of the enumeration context will be released.
+ *
+ **/
 void udev_enumerate_unref(struct udev_enumerate *udev_enumerate)
 {
        if (udev_enumerate == NULL)
@@ -84,6 +113,12 @@ void udev_enumerate_unref(struct udev_enumerate *udev_enumerate)
        free(udev_enumerate);
 }
 
+/**
+ * udev_enumerate_get_udev:
+ * @udev_enumerate: context
+ *
+ * Returns: the udev library context.
+ */
 struct udev *udev_enumerate_get_udev(struct udev_enumerate *udev_enumerate)
 {
        if (udev_enumerate == NULL)

diff --git a/libudev/libudev-list.c b/libudev/libudev-list.c
index bd9792ad6cc0106bde0cbc8d9ab2610d3fb15ca1..f6637fc92d9950bbe1553908c12e31a464b7f788 100644 (file)
--- a/libudev/libudev-list.c
+++ b/libudev/libudev-list.c
@@ -19,10 +19,18 @@
 #include "libudev.h"
 #include "libudev-private.h"
 
+/**
+ * SECTION:libudev-list
+ * @short_description: list operation
+ *
+ * Libudev list operations.
+ */
+
 /**
  * udev_list_entry:
  *
- * One entry in a list, containing a name and an optional value.
+ * Opaque object representing one entry in a list. An entry contains
+ * contains a name, and optionally a value.
  */
 struct udev_list_entry {
        struct udev_list_node node;

diff --git a/libudev/libudev-monitor.c b/libudev/libudev-monitor.c
index 5c4e8ca04ab6159710e70119c8c86490be1779bd..c38edddc39ff638e0e56016b49c2dc24a7a012be 100644 (file)
--- a/libudev/libudev-monitor.c
+++ b/libudev/libudev-monitor.c
@@ -27,6 +27,19 @@
 #include "libudev.h"
 #include "libudev-private.h"
 
+/**
+ * SECTION:libudev-monitor
+ * @short_description: device event source
+ *
+ * Connects to a device event source.
+ */
+
+/**
+/**
+ * udev_monitor:
+ *
+ * Opaque object handling one event source.
+ */
 struct udev_monitor {
        struct udev *udev;
        int refcount;
@@ -227,6 +240,14 @@ static inline void bpf_jmp(struct sock_filter *inss, unsigned int *i,
        (*i)++;
 }
 
+/**
+ * udev_monitor_filter_update:
+ * @udev_monitor: monitor
+ *
+ * Update the installed filter. This might only be needed, if the filter was removed or changed.
+ *
+ * Returns: 0 on success, otherwise a negative error value.
+ */
 int udev_monitor_filter_update(struct udev_monitor *udev_monitor)
 {
        static struct sock_filter ins[256];
@@ -290,7 +311,14 @@ int udev_monitor_allow_unicast_sender(struct udev_monitor *udev_monitor, struct
        udev_monitor->snl_trusted_sender.nl_pid = sender->snl.nl_pid;
        return 0;
 }
-
+/**
+ * udev_monitor_enable_receiving:
+ * @udev_monitor: the monitor which should receive events
+ *
+ * Binds the @udev_monitor socket to the event source.
+ *
+ * Returns: 0 on success, otherwise a negative error value.
+ */
 int udev_monitor_enable_receiving(struct udev_monitor *udev_monitor)
 {
        int err;
@@ -739,6 +767,16 @@ int udev_monitor_send_device(struct udev_monitor *udev_monitor,
        return count;
 }
 
+/**
+ * udev_monitor_filter_add_match_subsystem_devtype:
+ * @udev_monitor: the monitor
+ * @subsystem: the subsystem value to match the incoming devices against
+ * @devtype: the devtype value to matvh the incoming devices against
+ *
+ * The filter must be installed before the monitor is switched to listening mode.
+ *
+ * Returns: 0 on success, otherwise a negative error value.
+ */
 int udev_monitor_filter_add_match_subsystem_devtype(struct udev_monitor *udev_monitor, const char *subsystem, const char *devtype)
 {
        if (udev_monitor == NULL)
@@ -751,6 +789,14 @@ int udev_monitor_filter_add_match_subsystem_devtype(struct udev_monitor *udev_mo
        return 0;
 }
 
+/**
+ * udev_monitor_filter_remove:
+ * @udev_monitor: monitor
+ *
+ * Remove all filters from monitor.
+ *
+ * Returns: 0 on success, otherwise a negative error value.
+ */
 int udev_monitor_filter_remove(struct udev_monitor *udev_monitor)
 {
        static struct sock_fprog filter = { 0, NULL };

diff --git a/libudev/libudev-queue.c b/libudev/libudev-queue.c
index cf1ddf3a07397bc4926bc74565b7078ff9bb1ed3..bfd90975069eada8bdab949f0ddbb1128e2554b2 100644 (file)
--- a/libudev/libudev-queue.c
+++ b/libudev/libudev-queue.c
@@ -24,6 +24,21 @@
 #include "libudev.h"
 #include "libudev-private.h"
 
+/**
+ * SECTION:libudev-queue
+ * @short_description: access to currently active events
+ *
+ * The udev daemon processes event asynchronously. All events wich do not have
+ * interdependencies are run in parallel. This exports the current state of the
+ * event processing queue, and the currently event sequence numbers from the kernel
+ * and the udev daemon.
+ */
+
+/**
+ * udev_queue:
+ *
+ * Opaque object representing the current event queue in the udev daemon.
+ */
 struct udev_queue {
        struct udev *udev;
        int refcount;

diff --git a/libudev/libudev.c b/libudev/libudev.c
index d197ba7b1930ab9cac59e928ab82a56bc6537a28..f6fdcb2dfdda6ac4adc6abc5f9eda163cdd2bb2d 100644 (file)
--- a/libudev/libudev.c
+++ b/libudev/libudev.c
@@ -21,10 +21,18 @@
 #include "libudev.h"
 #include "libudev-private.h"
 
+/**
+ * SECTION:libudev
+ * @short_description: libudev context
+ *
+ * The context contains the default values read from the udev config file,
+ * and is passed to all library operations.
+ */
+
 /**
  * udev:
  *
- * Library context, passed to all operations.
+ * Opaque object representing the library context.
  */
 struct udev {
        int refcount;