From ce1d6d7fb47582588cfbcf0baba0c58e42a90ca6 Mon Sep 17 00:00:00 2001
From: Kay Sievers <kay.sievers@vrfy.org>
Date: Mon, 15 Jun 2009 17:09:43 +0200
Subject: [PATCH] libudev: doc - add section headers

---
 libudev/libudev-device.c    | 14 +++++++++--
 libudev/libudev-enumerate.c | 35 +++++++++++++++++++++++++++
 libudev/libudev-list.c      | 10 +++++++-
 libudev/libudev-monitor.c   | 48 ++++++++++++++++++++++++++++++++++++-
 libudev/libudev-queue.c     | 15 ++++++++++++
 libudev/libudev.c           | 10 +++++++-
 6 files changed, 127 insertions(+), 5 deletions(-)

diff --git a/libudev/libudev-device.c b/libudev/libudev-device.c
index aef62567341..9965972b328 100644
--- 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 63f84062b20..08f4af0ee78 100644
--- 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 bd9792ad6cc..f6637fc92d9 100644
--- 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 5c4e8ca04ab..c38edddc39f 100644
--- 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 cf1ddf3a073..bfd90975069 100644
--- 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 d197ba7b193..f6fdcb2dfdd 100644
--- 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;