From: Kay Sievers <kay.sievers@vrfy.org>
Date: Mon, 15 Jun 2009 11:22:38 +0000 (+0200)
Subject: libudev: update documentation
X-Git-Tag: 174~980
X-Git-Url: https://err.no/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1e5113228f8c5cde04b03616485e0c4ce54c3320;p=systemd

libudev: update documentation
---

diff --git a/libudev/libudev-device.c b/libudev/libudev-device.c
index 96cc2dba..aef62567 100644
--- a/libudev/libudev-device.c
+++ b/libudev/libudev-device.c
@@ -23,6 +23,11 @@
 #include "libudev.h"
 #include "libudev-private.h"
 
+/**
+ * udev_device:
+ *
+ * Representation of a kernel sys device.
+ */
 struct udev_device {
 	struct udev *udev;
 	struct udev_device *parent_device;
@@ -341,6 +346,23 @@ struct udev_device *udev_device_new_from_syspath(struct udev *udev, const char *
 	return udev_device;
 }
 
+/**
+ * udev_device_new_from_devnum:
+ * @udev: udev library context
+ * @type: char or block device
+ * @devnum: device major/minor number
+ *
+ * Create new udev device, and fill in information from the sys
+ * device and the udev database entry. The device is looked up
+ * by its major/minor number. Character and block device numbers
+ * are not unique across the two types, they do not share the same
+ * range of numbers.
+ *
+ * The initial refcount is 1, and needs to be decremented to
+ * release the resources of the udev device.
+ *
+ * Returns: a new udev device, or #NULL, if it does not exist
+ **/
 struct udev_device *udev_device_new_from_devnum(struct udev *udev, char type, dev_t devnum)
 {
 	char path[UTIL_PATH_SIZE];
@@ -392,6 +414,22 @@ struct udev_device *udev_device_new_from_devnum(struct udev *udev, char type, de
 	return device;
 }
 
+/**
+ * udev_device_new_from_subsystem_sysname:
+ * @udev: udev library context
+ * @subsystem: the subsytem of the device
+ * @sysname: the name of the device
+ *
+ * Create new udev device, and fill in information from the sys
+ * device and the udev database entry. The device is looked up
+ * by the subsytem and name string of the device, like "mem",
+ * "zero", or "block", "sda".
+ *
+ * The initial refcount is 1, and needs to be decremented to
+ * release the resources of the udev device.
+ *
+ * Returns: a new udev device, or #NULL, if it does not exist
+ **/
 struct udev_device *udev_device_new_from_subsystem_sysname(struct udev *udev, const char *subsystem, const char *sysname)
 {
 	char path_full[UTIL_PATH_SIZE];
@@ -495,6 +533,25 @@ static struct udev_device *device_new_from_parent(struct udev_device *udev_devic
 	return NULL;
 }
 
+/**
+ * udev_device_get_parent:
+ * @udev_device: the device to start searching from
+ *
+ * Find the next parent device, and fill in information from the sys
+ * device and the udev database entry.
+ *
+ * The returned the device is not referenced. It is attached to the
+ * child device, and will be cleaned up when the child device
+ * is cleaned up.
+ *
+ * It is not neccessarily just the upper level directory, empty or not
+ * recognized sys directories are ignored.
+ *
+ * It can be called as many times as needed, without caring about
+ * references.
+ *
+ * Returns: a new udev device, or #NULL, if it no parent exist.
+ **/
 struct udev_device *udev_device_get_parent(struct udev_device *udev_device)
 {
 	if (udev_device == NULL)
@@ -508,6 +565,25 @@ struct udev_device *udev_device_get_parent(struct udev_device *udev_device)
 	return udev_device->parent_device;
 }
 
+/**
+ * udev_device_get_parent_with_subsystem_devtype:
+ * @udev_device: udev device to start searching from
+ * @subsystem: the subsytem of the device
+ * @devtype: the type (DEVTYPE) of the device
+ *
+ * Find the next parent device, with a matching subsystem and devtype
+ * value, and fill in information from the sys device and the udev
+ * database entry.
+ *
+ * The returned the device is not referenced. It is attached to the
+ * child device, and will be cleaned up when the child device
+ * is cleaned up.
+ *
+ * It can be called as many times as needed, without caring about
+ * references.
+ *
+ * Returns: a new udev device, or #NULL, if no matching parent exists.
+ **/
 struct udev_device *udev_device_get_parent_with_subsystem_devtype(struct udev_device *udev_device, const char *subsystem, const char *devtype)
 {
 	struct udev_device *parent;
@@ -631,6 +707,12 @@ const char *udev_device_get_syspath(struct udev_device *udev_device)
 	return udev_device->syspath;
 }
 
+/**
+ * udev_device_get_sysname:
+ * @udev_device: udev device
+ *
+ * Returns: the sys name of the device device
+ **/
 const char *udev_device_get_sysname(struct udev_device *udev_device)
 {
 	if (udev_device == NULL)
@@ -638,6 +720,12 @@ const char *udev_device_get_sysname(struct udev_device *udev_device)
 	return udev_device->sysname;
 }
 
+/**
+ * udev_device_get_sysnum:
+ * @udev_device: udev device
+ *
+ * Returns: the trailing number of of the device name
+ **/
 const char *udev_device_get_sysnum(struct udev_device *udev_device)
 {
 	if (udev_device == NULL)
@@ -790,6 +878,12 @@ struct udev_list_entry *udev_device_get_properties_list_entry(struct udev_device
 	return udev_list_get_entry(&udev_device->properties_list);
 }
 
+/**
+ * udev_device_get_driver:
+ * @udev_device: udev device
+ *
+ * Returns: the driver string or #NULL, if ther is no driver attached.
+ **/
 const char *udev_device_get_driver(struct udev_device *udev_device)
 {
 	char driver[UTIL_NAME_SIZE];
@@ -804,6 +898,12 @@ const char *udev_device_get_driver(struct udev_device *udev_device)
 	return udev_device->driver;
 }
 
+/**
+ * udev_device_get_devnum:
+ * @udev_device: udev device
+ *
+ * Returns: the device major/minor number.
+ **/
 dev_t udev_device_get_devnum(struct udev_device *udev_device)
 {
 	if (udev_device == NULL)
@@ -813,6 +913,16 @@ dev_t udev_device_get_devnum(struct udev_device *udev_device)
 	return udev_device->devnum;
 }
 
+/**
+ * udev_device_get_action:
+ * @udev_device: udev device
+ *
+ * This is only valid if the device was received through a monitor. Devices read from
+ * sys do not have an action string. Usual actions are: add, remove, change, online,
+ * offline.
+ *
+ * Returns: the kernel action value, or #NULL if there is no action value available.
+ **/
 const char *udev_device_get_action(struct udev_device *udev_device)
 {
 	if (udev_device == NULL)
@@ -820,6 +930,15 @@ const char *udev_device_get_action(struct udev_device *udev_device)
 	return udev_device->action;
 }
 
+/**
+ * udev_device_get_devnum:
+ * @udev_device: udev device
+ *
+ * This is only valid if the device was received through a monitor. Devices read from
+ * sys do not have a sequence number.
+ *
+ * Returns: the kernel event sequence number, or 0 if there is no sequence number available.
+ **/
 unsigned long long int udev_device_get_seqnum(struct udev_device *udev_device)
 {
 	if (udev_device == NULL)
@@ -827,6 +946,16 @@ unsigned long long int udev_device_get_seqnum(struct udev_device *udev_device)
 	return udev_device->seqnum;
 }
 
+/**
+ * udev_device_get_sysattr_value:
+ * @udev_device: udev device
+ * @sysattr: attribute name
+ *
+ * The retrieved value is cached in the device. Repeated reads will return the same
+ * value and not open the attribute again.
+ *
+ * Returns: the content of a sys attribute file, or #NULL if there is no sys attribute value.
+ **/
 const char *udev_device_get_sysattr_value(struct udev_device *udev_device, const char *sysattr)
 {
 	struct udev_list_entry *list_entry;
@@ -1025,6 +1154,13 @@ struct udev_list_entry *udev_device_add_property_from_string(struct udev_device
 	return udev_device_add_property(udev_device, name, val);
 }
 
+/**
+ * udev_device_get_property_value:
+ * @udev_device: udev device
+ * @key: property name
+ *
+ * Returns: the value of a device property, or #NULL if there is no such property.
+ **/
 const char *udev_device_get_property_value(struct udev_device *udev_device, const char *key)
 {
 	struct udev_list_entry *list_entry;
diff --git a/libudev/libudev-list.c b/libudev/libudev-list.c
index 182d75aa..bd9792ad 100644
--- a/libudev/libudev-list.c
+++ b/libudev/libudev-list.c
@@ -19,6 +19,11 @@
 #include "libudev.h"
 #include "libudev-private.h"
 
+/**
+ * udev_list_entry:
+ *
+ * One entry in a list, containing a name and an optional value.
+ */
 struct udev_list_entry {
 	struct udev_list_node node;
 	struct udev *udev;
@@ -180,6 +185,12 @@ struct udev_list_entry *udev_list_get_entry(struct udev_list_node *list)
 	return list_node_to_entry(list->next);
 }
 
+/**
+ * udev_list_entry_get_next:
+ * @list_entry: current entry
+ *
+ * Returns: the next entry from the list, #NULL is no more entries are found.
+ */
 struct udev_list_entry *udev_list_entry_get_next(struct udev_list_entry *list_entry)
 {
 	struct udev_list_node *next;
@@ -193,6 +204,13 @@ struct udev_list_entry *udev_list_entry_get_next(struct udev_list_entry *list_en
 	return list_node_to_entry(next);
 }
 
+/**
+ * udev_list_entry_get_by_name:
+ * @list_entry: current entry
+ * @name: name string to match
+ *
+ * Returns: the entry where @name matched, #NULL if no matching entry is found.
+ */
 struct udev_list_entry *udev_list_entry_get_by_name(struct udev_list_entry *list_entry, const char *name)
 {
 	struct udev_list_entry *entry;
@@ -206,6 +224,12 @@ struct udev_list_entry *udev_list_entry_get_by_name(struct udev_list_entry *list
 	return NULL;
 }
 
+/**
+ * udev_list_entry_get_name:
+ * @list_entry: current entry
+ *
+ * Returns: the name string of this entry.
+ */
 const char *udev_list_entry_get_name(struct udev_list_entry *list_entry)
 {
 	if (list_entry == NULL)
@@ -213,6 +237,12 @@ const char *udev_list_entry_get_name(struct udev_list_entry *list_entry)
 	return list_entry->name;
 }
 
+/**
+ * udev_list_entry_get_value:
+ * @list_entry: current entry
+ *
+ * Returns: the value string of this entry.
+ */
 const char *udev_list_entry_get_value(struct udev_list_entry *list_entry)
 {
 	if (list_entry == NULL)
diff --git a/libudev/libudev.c b/libudev/libudev.c
index 66452985..d197ba7b 100644
--- a/libudev/libudev.c
+++ b/libudev/libudev.c
@@ -21,6 +21,11 @@
 #include "libudev.h"
 #include "libudev-private.h"
 
+/**
+ * udev:
+ *
+ * Library context, passed to all operations.
+ */
 struct udev {
 	int refcount;
 	void (*log_fn)(struct udev *udev,
@@ -54,6 +59,15 @@ static void log_stderr(struct udev *udev,
 	vfprintf(stderr, format, args);
 }
 
+/**
+ * udev_get_userdata:
+ * @udev: udev library context
+ *
+ * Retrieve stored data pointer from library context. This might be useful
+ * to access from callbacks.
+ *
+ * Returns: stored userdata
+ **/
 void *udev_get_userdata(struct udev *udev)
 {
 	if (udev == NULL)
@@ -61,6 +75,13 @@ void *udev_get_userdata(struct udev *udev)
 	return udev->userdata;
 }
 
+/**
+ * udev_set_userdata:
+ * @udev: udev library context
+ * @userdata: data pointer
+ *
+ * Store custom @userdata in the library context.
+ **/
 void udev_set_userdata(struct udev *udev, void *userdata)
 {
 	if (udev == NULL)
@@ -71,7 +92,8 @@ void udev_set_userdata(struct udev *udev, void *userdata)
 /**
  * udev_new:
  *
- * Create udev library context.
+ * Create udev library context. This reads the udev configuration
+ * file, and fills in the default values.
  *
  * The initial refcount is 1, and needs to be decremented to
  * release the resources of the udev library context.
@@ -293,11 +315,28 @@ void udev_set_log_fn(struct udev *udev,
 	info(udev, "custom logging function %p registered\n", udev);
 }
 
+/**
+ * udev_get_log_priority:
+ * @udev: udev library context
+ *
+ * The initial syslog priortity is read from the udev config file
+ * at startup.
+ *
+ * Returns: the current syslog priority
+ **/
 int udev_get_log_priority(struct udev *udev)
 {
 	return udev->log_priority;
 }
 
+/**
+ * udev_set_log_priority:
+ * @udev: udev library context
+ * @priority: the new syslog priority
+ *
+ * Set the current syslog priority. The value controls which messages
+ * are send to syslog.
+ **/
 void udev_set_log_priority(struct udev *udev, int priority)
 {
 	char num[32];
diff --git a/libudev/libudev.h b/libudev/libudev.h
index ffeb80f8..8b5391c0 100644
--- a/libudev/libudev.h
+++ b/libudev/libudev.h
@@ -47,10 +47,17 @@ struct udev_list_entry *udev_list_entry_get_next(struct udev_list_entry *list_en
 struct udev_list_entry *udev_list_entry_get_by_name(struct udev_list_entry *list_entry, const char *name);
 const char *udev_list_entry_get_name(struct udev_list_entry *list_entry);
 const char *udev_list_entry_get_value(struct udev_list_entry *list_entry);
-#define udev_list_entry_foreach(entry, first) \
-	for (entry = first; \
-	     entry != NULL; \
-	     entry = udev_list_entry_get_next(entry))
+/**
+ * udev_list_entry_foreach:
+ * @list_entry: entry to store the current position
+ * @first_entry: first entry to start with
+ *
+ * Helper to iterate over all entries of a list.
+ */
+#define udev_list_entry_foreach(list_entry, first_entry) \
+	for (list_entry = first_entry; \
+	     list_entry != NULL; \
+	     list_entry = udev_list_entry_get_next(list_entry))
 
 /*
  * udev_device