chiark / gitweb /
libudev: doc - add section headers
authorKay Sievers <kay.sievers@vrfy.org>
Mon, 15 Jun 2009 15:09:43 +0000 (17:09 +0200)
committerKay Sievers <kay.sievers@vrfy.org>
Mon, 15 Jun 2009 15:09:43 +0000 (17:09 +0200)
libudev/libudev-device.c
libudev/libudev-enumerate.c
libudev/libudev-list.c
libudev/libudev-monitor.c
libudev/libudev-queue.c
libudev/libudev.c

index aef6256..9965972 100644 (file)
 #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)
 {
index 63f8406..08f4af0 100644 (file)
 
 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)
index bd9792a..f6637fc 100644 (file)
 #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;
index 5c4e8ca..c38eddd 100644 (file)
 #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 };
index cf1ddf3..bfd9097 100644 (file)
 #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;
index d197ba7..f6fdcb2 100644 (file)
 #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;