From: Peter Hutterer Date: Sat, 22 Jun 2013 09:44:03 +0000 (+1000) Subject: Documentation fixes X-Git-Tag: libevdev-0.2~93 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=960dc91844fc0fc30ed180dd2c6d70e927e8ceec;p=platform%2Fupstream%2Flibevdev.git Documentation fixes Signed-off-by: Peter Hutterer --- diff --git a/libevdev/libevdev.h b/libevdev/libevdev.h index 1729d69..9d2991e 100644 --- a/libevdev/libevdev.h +++ b/libevdev/libevdev.h @@ -79,17 +79,44 @@ * Abstraction functions to handle device capabilities, specificially * device propeties such as the name of the device and the bits * representing the events suppported by this device. + * + * The logical state returned may lag behind the physical state of the device. + * libevdev queries the device state on libevdev_set_fd() and then relies on + * the caller to parse events through libevdev_next_fd(). If a caller does not + * use libevdev_next_fd(), libevdev will not update the internal state of the + * device and thus returns outdated values. */ /** * @defgroup mt Multi-touch related functions - * Functions for querying multi-touch-related capabilities. + * Functions for querying multi-touch-related capabilities. MT devices + * following the kernel protocol B (using ABS_MT_SLOT) provide multiple touch + * points through so-called slots on the same axis. The slots are enumerated, + * a client reading from the device will first get an ABS_MT_SLOT event, then + * the values of axes changed in this slot. Multiple slots may be provided in + * before an EV_SYN event. + * + * As with @ref bits, the logical state of the device as seen by the library + * depends on the caller using libevdev_next_event(). */ /** * @defgroup kernel Modifying the appearance or capabilities of the device * - * Modifying the set of events reported by this device. + * Modifying the set of events reported by this device. By default, the + * libevdev device mirrors the kernel device, enabling only those bits + * exported by the kernel. This set of functions enable or disable bits as + * seen from the caller. + * + * Enabling an event type or code does not affect event reporting - a + * software-enabled event will not be generated by the physical hardware. + * Disabling an event will prevent libevdev from routing such events to the + * caller. Enabling and disabling event types and codes is at the library + * level and thus only affects the caller. + * + * If an event type or code is enabled at kernel-level, future users of this + * device will see this event enabled. Currently there is no option of + * disabling an event type or code at kernel-level. */ /** @@ -136,11 +163,11 @@ struct libevdev* libevdev_new(void); * * This is a shortcut for * - * 
+ * @code
  * int err;
  * struct libevdev *dev = libevdev_new();
  * err = libevdev_set_fd(dev, fd);
- *
+ * @endcode * * @param fd A file descriptor to the device in O_RDWR or O_RDONLY mode. * @@ -176,7 +203,7 @@ typedef void (*libevdev_log_func_t)(const char *format, va_list args); /** * Set a printf-style logging handler for library-internal logging. * - * @note This function may be called before libevdev_set_fd. + * @note This function may be called before libevdev_set_fd(). */ void libevdev_set_log_handler(struct libevdev *dev, libevdev_log_func_t logfunc); @@ -251,7 +278,7 @@ int libevdev_change_fd(struct libevdev* dev, int fd); /** * * @return The previously set fd, or -1 if none had been set previously. - * @note This function may be called before libevdev_set_fd. + * @note This function may be called before libevdev_set_fd(). */ int libevdev_get_fd(const struct libevdev* dev); @@ -287,7 +314,8 @@ int libevdev_next_event(struct libevdev *dev, unsigned int flags, struct input_e /** * @ingroup bits * - * @return The device name as read off the kernel device + * @return The device name as read off the kernel device. The name is never + * NULL but it may be the empty string. * * @note This function is signal-safe. */ @@ -361,7 +389,7 @@ int libevdev_get_driver_version(const struct libevdev *dev); /** * @ingroup bits * - * @return 1 if the device supports this event type, or 0 otherwise. + * @return 1 if the device provides this input property, or 0 otherwise. * * @note This function is signal-safe */ @@ -379,7 +407,7 @@ int libevdev_has_event_type(const struct libevdev *dev, unsigned int type); /** * @ingroup bits * - * @return 1 if the device supports this event type, or 0 otherwise. + * @return 1 if the device supports this event type and code, or 0 otherwise. * * @note This function is signal-safe. */ @@ -434,7 +462,7 @@ const struct input_absinfo* libevdev_get_abs_info(const struct libevdev *dev, un * * @note This function is signal-safe. * @note The value for ABS_MT_ events is undefined, use - * libevdev_get_slot_value instead + * libevdev_get_slot_value() instead * * @see libevdev_get_slot_value */ @@ -445,17 +473,18 @@ int libevdev_get_event_value(const struct libevdev *dev, unsigned int type, unsi * * Fetch the current value of the event type. This is a shortcut for * - * 
+ * @code
  *   if (libevdev_has_event_type(dev, t) && libevdev_has_event_code(dev, t, c))
  *       val = libevdev_get_event_value(dev, t, c);
- *
+ * @endcode * - * @return non-zero if the device supports this event code, or zero - * otherwise. On return of zero, value is unmodified. + * @return If the device supports this event type and code, the return value is + * non-zero and value is set to the current value of this axis. Otherwise, + * zero is returned and value is unmodified. * * @note This function is signal-safe. * @note The value for ABS_MT_ events is undefined, use - * libevdev_fetch_slot_value instead + * libevdev_fetch_slot_value() instead * * @see libevdev_fetch_slot_value */ @@ -467,11 +496,12 @@ int libevdev_fetch_event_value(const struct libevdev *dev, unsigned int type, un * Return the current value of the code for the given slot. * * The return value is undefined for a slot exceeding the available slots on - * the device, or for a device that does not have slots. + * the device, for a code that is not in the permitted ABS_MT range or for a + * device that does not have slots. * * @note This function is signal-safe. * @note The value for events other than ABS_MT_ is undefined, use - * libevdev_fetch_value instead + * libevdev_fetch_value() instead * * @see libevdev_get_value */ @@ -482,21 +512,19 @@ int libevdev_get_slot_value(const struct libevdev *dev, unsigned int slot, unsig * * Fetch the current value of the code for the given slot. This is a shortcut for * - * 
+ * @code
  *   if (libevdev_has_event_type(dev, EV_ABS) &&
  *       libevdev_has_event_code(dev, EV_ABS, c) &&
  *       slot < device->number_of_slots)
  *       val = libevdev_get_slot_value(dev, slot, c);
- *
+ * @endcode * - * @return non-zero if the device supports this event code, or zero - * otherwise. On return of zero, value is unmodified. + * @return If the device supports this event code, the return value is + * non-zero and value is set to the current value of this axis. Otherwise, or + * if the event code is not an ABS_MT_* event code, zero is returned and value + * is unmodified. * * @note This function is signal-safe. - * @note The value for ABS_MT_ events is undefined, use - * libevdev_fetch_slot_value instead - * - * @see libevdev_fetch_slot_value */ int libevdev_fetch_slot_value(const struct libevdev *dev, unsigned int slot, unsigned int code, int *value); @@ -508,7 +536,8 @@ int libevdev_fetch_slot_value(const struct libevdev *dev, unsigned int slot, uns * Note that the slot offset may be non-zero, use libevdev_get_abs_min() or * libevdev_get_abs_info() to get the minimum slot number. * - * @return The number of slots supported, or -1 + * @return The number of slots supported, or -1 if the device does not provide + * any slots */ int libevdev_get_num_slots(const struct libevdev *dev); @@ -530,9 +559,9 @@ int libevdev_get_current_slot(const struct libevdev *dev); * * Forcibly enable an event type on this device, even if the underlying * device does not support it. While this cannot make the device actually - * report such events, it will now return true for libevdev_has_event_type. + * report such events, it will now return true for libevdev_has_event_type(). * - * This is a local modification only affecting only this process and only + * This is a local modification only affecting only this representation of * this device. * * @param type The event type to enable (EV_ABS, EV_KEY, ...) @@ -549,15 +578,15 @@ int libevdev_enable_event_type(struct libevdev *dev, unsigned int type); * Forcibly disable an event type on this device, even if the underlying * device provides it, effectively muting all keys or axes. libevdev will * filter any events matching this type and none will reach the caller. - * libevdev_has_event_type will return false for this type. + * libevdev_has_event_type() will return false for this type. * * In most cases, a caller likely only wants to disable a single code, not - * the whole type. Use libevdev_disable_event_code for that. + * the whole type. Use libevdev_disable_event_code() for that. * - * This is a local modification only affecting only this process and only + * This is a local modification only affecting only this representation of * this device. * - * @param type The event type to enable (EV_ABS, EV_KEY, ...) + * @param type The event type to disable (EV_ABS, EV_KEY, ...) * * @return 0 on success or -1 otherwise * @@ -571,16 +600,16 @@ int libevdev_disable_event_type(struct libevdev *dev, unsigned int type); * * Forcibly enable an event type on this device, even if the underlying * device does not support it. While this cannot make the device actually - * report such events, it will now return true for libevdev_has_event_code. + * report such events, it will now return true for libevdev_has_event_code(). * * The last argument depends on the type and code: * - If type is EV_ABS, the vararg must be a pointer to a struct input_absinfo * containing the data for this axis. * - For all other types, the argument is ignored. * - * This function calls libevdev_enable_event_type if necessary. + * This function calls libevdev_enable_event_type() if necessary. * - * This is a local modification only affecting only this process and only + * This is a local modification only affecting only this representation of * this device. * * @param type The event type to enable (EV_ABS, EV_KEY, ...) @@ -600,16 +629,16 @@ int libevdev_enable_event_code(struct libevdev *dev, unsigned int type, unsigned * device provides it, effectively muting this key or axis. libevdev will * filter any events matching this type and code and none will reach the * caller. - * libevdev_has_event_code will return false for this code combination. + * libevdev_has_event_code() will return false for this code combination. * * Disabling all event codes for a given type will not disable the event - * type. Use libevdev_disable_event_type for that. + * type. Use libevdev_disable_event_type() for that. * - * This is a local modification only affecting only this process and only + * This is a local modification only affecting only this representation of * this device. * - * @param type The event type to enable (EV_ABS, EV_KEY, ...) - * @param code The event code to enable (ABS_X, REL_X, etc.) + * @param type The event type to disable (EV_ABS, EV_KEY, ...) + * @param code The event code to disable (ABS_X, REL_X, etc.) * * @return 0 on success or -1 otherwise * @@ -624,17 +653,16 @@ int libevdev_disable_event_code(struct libevdev *dev, unsigned int type, unsigne * * Forcibly enable an event type on this device, even if the underlying * device does not support it. While this cannot make the device actually - * report such events, it will now return true for libevdev_has_event_code. + * report such events, it will now return true for libevdev_has_event_code(). * * This will be written to the kernel. * * This cannot be undone, the kernel only allows to enable axes, not disable * them. * - * This function calls libevdev_kernel_enable_event_type if necessary. + * This function calls libevdev_kernel_enable_event_type() if necessary. * * @param type The event type to enable (EV_ABS, EV_KEY, ...) - * @param code The event code to enable (ABS_X, REL_X, etc.) */ int libevdev_kernel_enable_event_type(struct libevdev *dev, unsigned int type); @@ -643,14 +671,14 @@ int libevdev_kernel_enable_event_type(struct libevdev *dev, unsigned int type); * * Forcibly enable an event code on this device, even if the underlying * device does not support it. While this cannot make the device actually - * report such events, it will now return true for libevdev_has_event_code. + * report such events, it will now return true for libevdev_has_event_code(). * * This will be written to the kernel. * * This cannot be undone, the kernel only allows to enable axes, not disable * them. * - * This function calls libevdev_kernel_enable_event_type if necessary. + * This function calls libevdev_kernel_enable_event_type() if necessary. * * @param type The event type to enable (EV_ABS, EV_KEY, ...) * @param code The event code to enable (ABS_X, REL_X, etc.) @@ -699,7 +727,7 @@ const char * libevdev_get_event_code_name(unsigned int type, unsigned int code); * @note The list of names is compiled into libevdev. If the kernel adds new * defines for new properties libevdev will not automatically pick these up. * @note On older kernels input properties may not be defined and - * libevdev_get_input_prop_name will always return NULL + * libevdev_get_input_prop_name() will always return NULL */ const char * libevdev_get_input_prop_name(unsigned int prop); @@ -723,6 +751,8 @@ int libevdev_get_event_type_max(unsigned int type); * @param period If not null, set to the repeat period value * * @return 0 on success, -1 if this device does not have repeat settings. + * + * @note This function is signal-safe */ int libevdev_get_repeat(struct libevdev *dev, int *delay, int *period);