From 21dbe43aece5b6fc87860de175f067b56649e7d1 Mon Sep 17 00:00:00 2001 From: Kay Sievers Date: Fri, 20 Apr 2012 03:25:36 +0200 Subject: [PATCH] docs: hook-up gtk-doc to 'make check' --- docs/gudev/Makefile.am | 10 +++++----- docs/gudev/gudev-docs.xml | 10 ++++++++-- docs/gudev/gudev-sections.txt | 13 ------------- docs/libudev/Makefile.am | 4 ++-- docs/libudev/libudev-docs.xml | 3 ++- src/libudev/libudev-device.c | 29 ++++++++++++++++++++++++----- src/libudev/libudev-enumerate.c | 31 ++++++++++++++++++++++++++++--- src/libudev/libudev-list.c | 12 ++++++++++-- src/libudev/libudev-queue.c | 20 +++++++++++++++++--- src/libudev/libudev-util.c | 2 ++ 10 files changed, 98 insertions(+), 36 deletions(-) diff --git a/docs/gudev/Makefile.am b/docs/gudev/Makefile.am index f984eb5cb..11312b679 100644 --- a/docs/gudev/Makefile.am +++ b/docs/gudev/Makefile.am @@ -57,7 +57,7 @@ EXTRA_HFILES= # Header files to ignore when scanning. Use base file name, no paths # e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h -IGNORE_HFILES= +IGNORE_HFILES=gudevenumtypes.h gudevmarshal.h # Images to copy into HTML directory. # e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png @@ -83,8 +83,8 @@ GTKDOC_CFLAGS = \ -I$(top_builddir)/src/gudev GTKDOC_LIBS = \ - $(GLIB_LIBS) \ - $(top_builddir)/libgudev-1.0.la + $(GLIB_LIBS) \ + $(top_builddir)/libgudev-1.0.la # This includes the standard gtk-doc make rules, copied by gtkdocize. include $(top_srcdir)/gtk-doc.make @@ -100,8 +100,8 @@ EXTRA_DIST += version.xml.in # Comment this out if you want your docs-status tested during 'make check' if ENABLE_GTK_DOC -#TESTS_ENVIRONMENT = cd $(srcsrc) -#TESTS = $(GTKDOC_CHECK) +TESTS_ENVIRONMENT = cd $(top_srcdir) +TESTS = $(GTKDOC_CHECK) endif install-data-hook: diff --git a/docs/gudev/gudev-docs.xml b/docs/gudev/gudev-docs.xml index 30be83669..847d24252 100644 --- a/docs/gudev/gudev-docs.xml +++ b/docs/gudev/gudev-docs.xml @@ -33,8 +33,9 @@ - - Index + + API Index + @@ -42,5 +43,10 @@ + + Index of deprecated API + + + diff --git a/docs/gudev/gudev-sections.txt b/docs/gudev/gudev-sections.txt index 213e1a746..b25c13bcb 100644 --- a/docs/gudev/gudev-sections.txt +++ b/docs/gudev/gudev-sections.txt @@ -98,16 +98,3 @@ G_UDEV_ENUMERATOR_GET_CLASS GUdevEnumeratorPrivate - -
-gudevmarshal - -g_udev_marshal_VOID__STRING_OBJECT -
- -
-gudevenumtypes - -G_TYPE_UDEV_DEVICE_TYPE -g_udev_device_type_get_type -
diff --git a/docs/libudev/Makefile.am b/docs/libudev/Makefile.am index 0aff6008f..0b01274aa 100644 --- a/docs/libudev/Makefile.am +++ b/docs/libudev/Makefile.am @@ -94,8 +94,8 @@ EXTRA_DIST += version.xml.in # Comment this out if you want your docs-status tested during 'make check' if ENABLE_GTK_DOC -#TESTS_ENVIRONMENT = cd $(srcsrc) -#TESTS = $(GTKDOC_CHECK) +TESTS_ENVIRONMENT = cd $(top_srcdir) +TESTS = $(GTKDOC_CHECK) endif install-data-hook: diff --git a/docs/libudev/libudev-docs.xml b/docs/libudev/libudev-docs.xml index 2d856ced0..d8248aaaf 100644 --- a/docs/libudev/libudev-docs.xml +++ b/docs/libudev/libudev-docs.xml @@ -29,10 +29,11 @@ + Index - + diff --git a/src/libudev/libudev-device.c b/src/libudev/libudev-device.c index 6a2b1d039..97cf6654e 100644 --- a/src/libudev/libudev-device.c +++ b/src/libudev/libudev-device.c @@ -136,7 +136,9 @@ static int udev_device_set_ifindex(struct udev_device *udev_device, int ifindex) * udev_device_get_devnum: * @udev_device: udev device * - * Returns: the device major/minor number. + * Get the device major/minor number. + * + * Returns: the dev_t number. **/ _public_ dev_t udev_device_get_devnum(struct udev_device *udev_device) { @@ -185,7 +187,9 @@ static int udev_device_set_devpath_old(struct udev_device *udev_device, const ch * udev_device_get_driver: * @udev_device: udev device * - * Returns: the driver string, or #NULL if there is no driver attached. + * Get the kernel driver name. + * + * Returns: the driver name string, or #NULL if there is no driver attached. **/ _public_ const char *udev_device_get_driver(struct udev_device *udev_device) { @@ -440,7 +444,9 @@ int udev_device_add_property_from_string_parse_finish(struct udev_device *udev_d * @udev_device: udev device * @key: property name * - * Returns: the value of a device property, or #NULL if there is no such property. + * Get the value of a given property. + * + * Returns: the property string, or #NULL if there is no such property. **/ _public_ const char *udev_device_get_property_value(struct udev_device *udev_device, const char *key) { @@ -1081,7 +1087,9 @@ _public_ const char *udev_device_get_syspath(struct udev_device *udev_device) * udev_device_get_sysname: * @udev_device: udev device * - * Returns: the sys name of the device device + * Get the kernel device name in /sys. + * + * Returns: the name string of the device device **/ _public_ const char *udev_device_get_sysname(struct udev_device *udev_device) { @@ -1094,7 +1102,9 @@ _public_ const char *udev_device_get_sysname(struct udev_device *udev_device) * udev_device_get_sysnum: * @udev_device: udev device * - * Returns: the trailing number of of the device name + * Get the instance number of the device. + * + * Returns: the trailing number string of of the device name **/ _public_ const char *udev_device_get_sysnum(struct udev_device *udev_device) { @@ -1583,6 +1593,15 @@ _public_ struct udev_list_entry *udev_device_get_tags_list_entry(struct udev_dev return udev_list_get_entry(&udev_device->tags_list); } +/** + * udev_device_has_tag: + * @udev_device: udev device + * @tag: tag name + * + * Check if a given device has a certain tag associated. + * + * Returns: 1 if the tag is found. 0 otherwise. + **/ _public_ int udev_device_has_tag(struct udev_device *udev_device, const char *tag) { struct udev_list_entry *list_entry; diff --git a/src/libudev/libudev-enumerate.c b/src/libudev/libudev-enumerate.c index 4725912c3..9e6f4677e 100644 --- a/src/libudev/libudev-enumerate.c +++ b/src/libudev/libudev-enumerate.c @@ -65,7 +65,9 @@ struct udev_enumerate { * udev_enumerate_new: * @udev: udev library context * - * Returns: an enumeration context + * Create an enumeration context to scan /sys. + * + * Returns: an enumeration context. **/ _public_ struct udev_enumerate *udev_enumerate_new(struct udev *udev) { @@ -138,7 +140,9 @@ _public_ void udev_enumerate_unref(struct udev_enumerate *udev_enumerate) * udev_enumerate_get_udev: * @udev_enumerate: context * - * Returns: the udev library context. + * Get the udev library context. + * + * Returns: a pointer to the context. */ _public_ struct udev *udev_enumerate_get_udev(struct udev_enumerate *udev_enumerate) { @@ -243,7 +247,9 @@ static size_t devices_delay_later(struct udev *udev, const char *syspath) * udev_enumerate_get_list_entry: * @udev_enumerate: context * - * Returns: the first entry of the sorted list of device paths. + * Get the first entry of the sorted list of device paths. + * + * Returns: a udev_list_entry. */ _public_ struct udev_list_entry *udev_enumerate_get_list_entry(struct udev_enumerate *udev_enumerate) { @@ -321,6 +327,8 @@ _public_ struct udev_list_entry *udev_enumerate_get_list_entry(struct udev_enume * @udev_enumerate: context * @subsystem: filter for a subsystem of the device to include in the list * + * Match only devices belonging to a certain kernel subsystem. + * * Returns: 0 on success, otherwise a negative error value. */ _public_ int udev_enumerate_add_match_subsystem(struct udev_enumerate *udev_enumerate, const char *subsystem) @@ -339,6 +347,8 @@ _public_ int udev_enumerate_add_match_subsystem(struct udev_enumerate *udev_enum * @udev_enumerate: context * @subsystem: filter for a subsystem of the device to exclude from the list * + * Match only devices not belonging to a certain kernel subsystem. + * * Returns: 0 on success, otherwise a negative error value. */ _public_ int udev_enumerate_add_nomatch_subsystem(struct udev_enumerate *udev_enumerate, const char *subsystem) @@ -358,6 +368,8 @@ _public_ int udev_enumerate_add_nomatch_subsystem(struct udev_enumerate *udev_en * @sysattr: filter for a sys attribute at the device to include in the list * @value: optional value of the sys attribute * + * Match only devices with a certain /sys device attribute. + * * Returns: 0 on success, otherwise a negative error value. */ _public_ int udev_enumerate_add_match_sysattr(struct udev_enumerate *udev_enumerate, const char *sysattr, const char *value) @@ -377,6 +389,8 @@ _public_ int udev_enumerate_add_match_sysattr(struct udev_enumerate *udev_enumer * @sysattr: filter for a sys attribute at the device to exclude from the list * @value: optional value of the sys attribute * + * Match only devices not having a certain /sys device attribute. + * * Returns: 0 on success, otherwise a negative error value. */ _public_ int udev_enumerate_add_nomatch_sysattr(struct udev_enumerate *udev_enumerate, const char *sysattr, const char *value) @@ -416,6 +430,8 @@ exit: * @property: filter for a property of the device to include in the list * @value: value of the property * + * Match only devices with a certain property. + * * Returns: 0 on success, otherwise a negative error value. */ _public_ int udev_enumerate_add_match_property(struct udev_enumerate *udev_enumerate, const char *property, const char *value) @@ -434,6 +450,8 @@ _public_ int udev_enumerate_add_match_property(struct udev_enumerate *udev_enume * @udev_enumerate: context * @tag: filter for a tag of the device to include in the list * + * Match only devices with a certain tag. + * * Returns: 0 on success, otherwise a negative error value. */ _public_ int udev_enumerate_add_match_tag(struct udev_enumerate *udev_enumerate, const char *tag) @@ -503,6 +521,8 @@ _public_ int udev_enumerate_add_match_is_initialized(struct udev_enumerate *udev * @udev_enumerate: context * @sysname: filter for the name of the device to include in the list * + * Match only devices with a given /sys device name. + * * Returns: 0 on success, otherwise a negative error value. */ _public_ int udev_enumerate_add_match_sysname(struct udev_enumerate *udev_enumerate, const char *sysname) @@ -867,6 +887,9 @@ static int scan_devices_all(struct udev_enumerate *udev_enumerate) * udev_enumerate_scan_devices: * @udev_enumerate: udev enumeration context * + * Scan /sys for all devices which match the given filters. No matches + * will return all currently available devices. + * * Returns: 0 on success, otherwise a negative error value. **/ _public_ int udev_enumerate_scan_devices(struct udev_enumerate *udev_enumerate) @@ -890,6 +913,8 @@ _public_ int udev_enumerate_scan_devices(struct udev_enumerate *udev_enumerate) * udev_enumerate_scan_subsystems: * @udev_enumerate: udev enumeration context * + * Scan /sys for all kernel subsystems, including buses, classes, drivers. + * * Returns: 0 on success, otherwise a negative error value. **/ _public_ int udev_enumerate_scan_subsystems(struct udev_enumerate *udev_enumerate) diff --git a/src/libudev/libudev-list.c b/src/libudev/libudev-list.c index 054c0a931..1fe46f3f2 100644 --- a/src/libudev/libudev-list.c +++ b/src/libudev/libudev-list.c @@ -261,7 +261,9 @@ struct udev_list_entry *udev_list_get_entry(struct udev_list *list) * udev_list_entry_get_next: * @list_entry: current entry * - * Returns: the next entry from the list, #NULL is no more entries are found. + * Get the next entry from the list. + * + * Returns: udev_list_entry, #NULL if no more entries are available. */ _public_ struct udev_list_entry *udev_list_entry_get_next(struct udev_list_entry *list_entry) { @@ -281,7 +283,9 @@ _public_ struct udev_list_entry *udev_list_entry_get_next(struct udev_list_entry * @list_entry: current entry * @name: name string to match * - * Returns: the entry where @name matched, #NULL if no matching entry is found. + * Lookup an entry in the list with a certain name. + * + * Returns: udev_list_entry, #NULL if no matching entry is found. */ _public_ struct udev_list_entry *udev_list_entry_get_by_name(struct udev_list_entry *list_entry, const char *name) { @@ -303,6 +307,8 @@ _public_ struct udev_list_entry *udev_list_entry_get_by_name(struct udev_list_en * udev_list_entry_get_name: * @list_entry: current entry * + * Get the name of a list entry. + * * Returns: the name string of this entry. */ _public_ const char *udev_list_entry_get_name(struct udev_list_entry *list_entry) @@ -316,6 +322,8 @@ _public_ const char *udev_list_entry_get_name(struct udev_list_entry *list_entry * udev_list_entry_get_value: * @list_entry: current entry * + * Get the value of list entry. + * * Returns: the value string of this entry. */ _public_ const char *udev_list_entry_get_value(struct udev_list_entry *list_entry) diff --git a/src/libudev/libudev-queue.c b/src/libudev/libudev-queue.c index ca2300230..e2e631918 100644 --- a/src/libudev/libudev-queue.c +++ b/src/libudev/libudev-queue.c @@ -142,7 +142,9 @@ unsigned long long int udev_get_kernel_seqnum(struct udev *udev) * udev_queue_get_kernel_seqnum: * @udev_queue: udev queue context * - * Returns: the current kernel event sequence number. + * Get the current kernel event sequence number. + * + * Returns: the sequence number. **/ _public_ unsigned long long int udev_queue_get_kernel_seqnum(struct udev_queue *udev_queue) { @@ -226,7 +228,9 @@ static FILE *open_queue_file(struct udev_queue *udev_queue, unsigned long long i * udev_queue_get_udev_seqnum: * @udev_queue: udev queue context * - * Returns: the last known udev event sequence number. + * Get the last known udev event sequence number. + * + * Returns: the sequence number. **/ _public_ unsigned long long int udev_queue_get_udev_seqnum(struct udev_queue *udev_queue) { @@ -258,6 +262,8 @@ _public_ unsigned long long int udev_queue_get_udev_seqnum(struct udev_queue *ud * udev_queue_get_udev_is_active: * @udev_queue: udev queue context * + * Check if udev is active on the system. + * * Returns: a flag indicating if udev is active. **/ _public_ int udev_queue_get_udev_is_active(struct udev_queue *udev_queue) @@ -277,6 +283,8 @@ _public_ int udev_queue_get_udev_is_active(struct udev_queue *udev_queue) * udev_queue_get_queue_is_empty: * @udev_queue: udev queue context * + * Check if udev is currently processing any events. + * * Returns: a flag indicating if udev is currently handling events. **/ _public_ int udev_queue_get_queue_is_empty(struct udev_queue *udev_queue) @@ -331,6 +339,8 @@ out: * @start: first event sequence number * @end: last event sequence number * + * Check if udev is currently processing any events in a given sequence number range. + * * Returns: a flag indicating if any of the sequence numbers in the given range is currently active. **/ _public_ int udev_queue_get_seqnum_sequence_is_finished(struct udev_queue *udev_queue, @@ -393,6 +403,8 @@ _public_ int udev_queue_get_seqnum_sequence_is_finished(struct udev_queue *udev_ * @udev_queue: udev queue context * @seqnum: sequence number * + * Check if udev is currently processing a given sequence number. + * * Returns: a flag indicating if the given sequence number is currently active. **/ _public_ int udev_queue_get_seqnum_is_finished(struct udev_queue *udev_queue, unsigned long long int seqnum) @@ -407,7 +419,9 @@ _public_ int udev_queue_get_seqnum_is_finished(struct udev_queue *udev_queue, un * udev_queue_get_queued_list_entry: * @udev_queue: udev queue context * - * Returns: the first entry of the list of queued events. + * Get the first entry of the list of queued events. + * + * Returns: a udev_list_entry. **/ _public_ struct udev_list_entry *udev_queue_get_queued_list_entry(struct udev_queue *udev_queue) { diff --git a/src/libudev/libudev-util.c b/src/libudev/libudev-util.c index aed4393d5..944d9dfcb 100644 --- a/src/libudev/libudev-util.c +++ b/src/libudev/libudev-util.c @@ -30,6 +30,8 @@ /** * SECTION:libudev-util * @short_description: utils + * + * Utilities useful when dealing with devices and device node names. */ int util_delete_path(struct udev *udev, const char *path) -- 2.30.2