From 25e5f5af08a9d8de8ec55884b6de7d86a25a6979 Mon Sep 17 00:00:00 2001 From: Mike Blumenkrantz Date: Sun, 23 May 2010 05:03:17 +0000 Subject: [PATCH] some dox tweaks SVN revision: 49151 --- legacy/eeze/src/lib/eeze_udev_find.c | 11 ++++++----- legacy/eeze/src/lib/eeze_udev_syspath.c | 14 +++++++------- legacy/eeze/src/lib/eeze_udev_walk.c | 2 +- legacy/eeze/src/lib/eeze_udev_watch.c | 13 +++++++++++-- 4 files changed, 25 insertions(+), 15 deletions(-) diff --git a/legacy/eeze/src/lib/eeze_udev_find.c b/legacy/eeze/src/lib/eeze_udev_find.c index 5b70f6815e..576581f1e7 100644 --- a/legacy/eeze/src/lib/eeze_udev_find.c +++ b/legacy/eeze/src/lib/eeze_udev_find.c @@ -17,7 +17,7 @@ extern _udev *udev; */ /** - * Returns a list of all syspaths that are (or should be) the same + * Returns a stringshared list of all syspaths that are (or should be) the same * device as the device pointed at by @p syspath. * * @param syspath The syspath of the device to find matches for @@ -99,7 +99,8 @@ eeze_udev_find_similar_from_syspath(const char *syspath) * @param syspath The syspath of the device to find matches for. * * This function will update @p list to include all devices matching - * devices with syspaths currently stored in @p list. + * devices with syspaths currently stored in @p list. All strings are + * stringshared. * * @ingroup find */ @@ -165,7 +166,7 @@ eeze_udev_find_unlisted_similar(Eina_List * list) * * @param type An @ref Eeze_Udev_Type or 0 * @param name A filter for the device name or NULL - * @return An Eina_List of matched devices or NULL on failure + * @return A stringshared Eina_List of matched devices or NULL on failure * * Return a list of syspaths (/sys/$syspath) for matching udev devices. * @@ -314,7 +315,7 @@ out: * @param subsystem The udev subsystem to filter by, or NULL * @param type "ID_INPUT_KEY", "ID_INPUT_MOUSE", "ID_INPUT_TOUCHPAD", NULL, etc * @param name A filter for the device name, or NULL - * @return A Eina_List* of matched devices or NULL on failure + * @return A stringshared Eina_List* of matched devices or NULL on failure * * Return a list of syspaths (/sys/$syspath) for matching udev devices. * Requires at least one filter. @@ -368,7 +369,7 @@ out: * @param sysattr The attribute to find * @param value Optional: the value that the attribute should have * - * @return A list of the devices found with the attribute + * @return A stringshared list of the devices found with the attribute * * @ingroup find */ diff --git a/legacy/eeze/src/lib/eeze_udev_syspath.c b/legacy/eeze/src/lib/eeze_udev_syspath.c index f5d93c5bae..42da688dfc 100644 --- a/legacy/eeze/src/lib/eeze_udev_syspath.c +++ b/legacy/eeze/src/lib/eeze_udev_syspath.c @@ -23,7 +23,7 @@ extern _udev *udev; * @param syspath The syspath of a device, with or without "/sys/" * @return The syspath of the parent device * - * Return a syspath (/sys/$syspath) for the parent device. + * Return a stringshared syspath (/sys/$syspath) for the parent device. * * @ingroup syspath */ @@ -55,7 +55,7 @@ eeze_udev_syspath_get_parent(const char *syspath) * Returns a list of all parent device syspaths for @p syspath. * * @param syspath The device to find parents of - * @return A list of the parent devices of @p syspath + * @return A stringshared list of the parent devices of @p syspath * * @ingroup syspath */ @@ -95,7 +95,7 @@ eeze_udev_syspath_get_parents(const char *syspath) * Get the /dev/ path from the /sys/ path. * * @param syspath The /sys/ path with or without the /sys/ - * @return A const char* with the /dev/ path or NULL on failure + * @return A stringshared char* with the /dev/ path or NULL on failure * * Takes /sys/$PATH and turns it into the corresponding "/dev/x/y". * @@ -132,7 +132,7 @@ eeze_udev_syspath_get_devpath(const char *syspath) * Get the subsystem of a device from the /sys/ path. * * @param syspath The /sys/ path with or without the /sys/ - * @return A const char* with the subsystem of the device or NULL on failure + * @return A stringshared char* with the subsystem of the device or NULL on failure * * Takes /sys/$PATH and returns the corresponding device subsystem, * such as "input" for keyboards/mice. @@ -168,7 +168,7 @@ eeze_udev_syspath_get_subsystem(const char *syspath) * * @param syspath The /sys/ path with or without the /sys/ * @param property The property to get; full list of these is a FIXME - * @return A const char* with the property or NULL on failure + * @return A stringshared char* with the property or NULL on failure * * @ingroup syspath */ @@ -203,7 +203,7 @@ eeze_udev_syspath_get_property(const char *syspath, const char *property) * * @param syspath The /sys/ path with or without the /sys/ * @param sysattr The sysattr to get; full list of these is a FIXME - * @return A const char* with the sysattr or NULL on failure + * @return A stringshared char* with the sysattr or NULL on failure * * @ingroup syspath */ @@ -375,7 +375,7 @@ eeze_udev_syspath_is_touchpad(const char *syspath) * Get the syspath of a device from the /dev/ path. * * @param devpath The /dev/ path of the device - * @return A const char* which corresponds to the /sys/ path of the device or NULL on failure + * @return A stringshared char* which corresponds to the /sys/ path of the device or NULL on failure * * Takes "/dev/path" and returns the corresponding /sys/ path (without the "/sys/") * diff --git a/legacy/eeze/src/lib/eeze_udev_walk.c b/legacy/eeze/src/lib/eeze_udev_walk.c index be2b202bba..6e044d09ab 100644 --- a/legacy/eeze/src/lib/eeze_udev_walk.c +++ b/legacy/eeze/src/lib/eeze_udev_walk.c @@ -82,7 +82,7 @@ eeze_udev_walk_check_sysattr(const char *syspath, const char *sysattr, * @param syspath The /sys/ path of the device to start at, with or without the /sys/ * @param sysattr The attribute to find * - * @return The value of @p sysattr if found, or NULL + * @return The stringshared value of @p sysattr if found, or NULL * * @ingroup walks */ diff --git a/legacy/eeze/src/lib/eeze_udev_watch.c b/legacy/eeze/src/lib/eeze_udev_watch.c index 344fd705d8..6fdb585966 100644 --- a/legacy/eeze/src/lib/eeze_udev_watch.c +++ b/legacy/eeze/src/lib/eeze_udev_watch.c @@ -30,7 +30,12 @@ struct _store_data /** * @defgroup watch Watch * - * These are functions which monitor udev for events. + * @brief These are functions which monitor udev for events. + * + * Eeze watches are simple: you specify a type of device to watch (or all devices), some events (or all) to watch for, a callback, + * and some data, and then udev watches those device types for events of the type you specified. Your callback is called with a + * syspath of the triggering device and the event that happened to the device, along with the data you associated with the watch and + * the watch object itself in case you want to stop the watch easily in a callback. * * @ingroup udev */ @@ -276,11 +281,15 @@ error: * @param type The @ref Eeze_Udev_Type to watch * @param event The events to watch; an OR list of @ref event (ie (EEZE_UDEV_EVENT_ADD | EEZE_UDEV_EVENT_REMOVE)), or 0 for all events * @param func The function to call when the watch receives data; - * must take (const char *device, const char *event_type, void *data, Eeze_Udev_Watch *watch) + * must take (const char *device, int event_type, void *data, Eeze_Udev_Watch *watch) * @param user_data Data to pass to the callback function * * @return A watch struct for the watch type specified, or NULL on failure * + * Eeze watches will monitor udev for changes of type(s) @p event to devices of type @p type. When these changes occur, the stringshared + * syspath of the device will be sent to function @p func, along with the bitmask of the event type which can be detected through + * binary &. + * * @ingroup watch */ EAPI Eeze_Udev_Watch *