Use doxygen instead of man pages

Doxygen is bad for man pages, but having an online API documentation
is better and easier to maintain.

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

1 files changed, 193 insertions, 13 deletions

diff --git a/libevdev/libevdev.h b/libevdev/libevdev.h
index 9f0e365..1729d69 100644
--- a/libevdev/libevdev.h
+++ b/libevdev/libevdev.h
@@ -27,28 +27,119 @@
 #include <linux/input.h>
 #include <stdarg.h>
 
+/**
+ * @mainpage
+ *
+ * libevdev is a library for handling evdev kernel devices. It abstracts
+ * the ioctls through type-safe interfaces and provides functions to change
+ * the appearance of the device.
+ *
+ * libevdev provides an interface for handling events, including most notably
+ * SYN_DROPPED events.
+ *
+ * libevdev is signal-safe for the majority of its operations. Check the API
+ * documentation to make sure, unless explicitly stated a call is <b>not</b>
+ * signal safe.
+ *
+ * libevdev does not attempt duplicate detection. Initializing two libevdev
+ * devices for the same fd is valid and behaves the same as for two different
+ * devices.
+ */
+
+/**
+ * @defgroup init Initialization and setup
+ *
+ * Initialization, initial setup and file descriptor handling.
+ * These functions are the main entry points for users of libevdev, usually a
+ * caller will use this series of calls:
+ *
+ * @code
+ * struct libevdev *dev;
+ * int err;
+ *
+ * dev = libevdev_new();
+ * if (!dev)
+ *    return ENOSPC;
+
+ * err = libevdev_set_fd(dev, fd);
+ * if (err < 0) {
+ *	printf("Failed (errno %d): %s\n", -err, strerror(-err));
+ *
+ * libevdev_free(dev);
+ * @endcode
+ *
+ * libevdev_set_fd() is the central call and initializes the internal structs
+ * for the device at the given fd. libevdev functions will fail if called
+ * before libevdev_set_fd() unless documented otherwise.
+ */
+
+/**
+ * @defgroup bits Querying device capabilities
+ *
+ * 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.
+ */
+
+/**
+ * @defgroup mt Multi-touch related functions
+ * Functions for querying multi-touch-related capabilities.
+ */
+
+/**
+ * @defgroup kernel Modifying the appearance or capabilities of the device
+ *
+ * Modifying the set of events reported by this device.
+ */
+
+/**
+ * @defgroup misc Miscellaneous helper functions
+ *
+ * Functions for printing or querying event ranges. The list of names is
+ * compiled into libevdev and will not change when the kernel changes. Adding
+ * or removing names requires a re-compilation of libevdev. Likewise, the max
+ * for each event type is compiled in and does not check the underlying
+ * kernel.
+ */
+
+/**
+ * @ingroup init
+ *
+ * Opaque struct representing an evdev device.
+ */
 struct libevdev;
 
 enum EvdevReadFlags {
     LIBEVDEV_READ_SYNC		= 1, /**< Process data in sync mode */
 };
 
-
 /**
- * Initialize a new libevdev device.
-*
+ * @ingroup init
+ *
+ * Initialize a new libevdev device. This function only allocates the
+ * required memory and initializes the struct to sane default values.
+ * To actually hook up the device to a kernel device, use
+ * libevdev_set_fd().
+ *
+ * Memory allocated through libevdev_new() must be released by the
+ * caller with libevdev_free().
+ *
  * @see libevdev_set_fd
+ * @see libevdev_free
  */
 struct libevdev* libevdev_new(void);
 
 /**
+ * @ingroup init
+ *
  * Initialize a new libevdev device from the given fd.
  *
  * This is a shortcut for
  *
  * <pre>
+ * int err;
  * struct libevdev *dev = libevdev_new();
- * libevdev_set_fd(dev, fd);
+ * err = libevdev_set_fd(dev, fd);
  * </pre>
  *
  * @param fd A file descriptor to the device in O_RDWR or O_RDONLY mode.
@@ -56,13 +147,18 @@ struct libevdev* libevdev_new(void);
  * @return On success, zero is returned and dev is set to the newly
  * allocated struct. On failure, a negative errno is returned and the value
  * of dev is undefined.
+ *
+ * @see libevdev_free
  */
 int libevdev_new_from_fd(int fd, struct libevdev **dev);
 
 /**
- * Clean up and free the libevdev struct.
+ * @ingroup init
  *
- * @note This function may be called before libevdev_set_fd.
+ * Clean up and free the libevdev struct. After completion, the <code>struct
+ * libevdev</code> is invalid and must not be used.
+ *
+ * @note This function may be called before libevdev_set_fd().
  */
 void libevdev_free(struct libevdev *dev);
 
@@ -108,15 +204,18 @@ enum EvdevGrabModes {
 int libevdev_grab(struct libevdev *dev, int grab);
 
 /**
+ * @ingroup init
+ *
  * Set the fd for this struct and initialize internal data.
- * The fd must be open for reading and ioctl.
+ * The fd must be in O_RDONLY or O_RDWR mode.
  *
- * This function may only be called once per device. If you need to re-read
- * a device, use libevdev_free and libevdev_new. If you need to change the
- * fd, use libevdev_change_fd.
+ * This function may only be called once per device. If the device changed and
+ * you need to re-read a device, use libevdev_free() and libevdev_new(). If
+ * you need to change the fd after closing and re-opening the same device, use
+ * libevdev_change_fd().
  *
  * Unless otherwise specified, libevdev function behavior is undefined until
- * a successfull call to libevdev_set_fd.
+ * a successfull call to libevdev_set_fd().
  *
  * @param fd The file descriptor for the device
  *
@@ -129,9 +228,17 @@ int libevdev_grab(struct libevdev *dev, int grab);
 int libevdev_set_fd(struct libevdev* dev, int fd);
 
 /**
- * Change the fd for this device, without re-reading the actual device.
+ * @ingroup init
  *
- * It is an error to call this function before calling libevdev_set_fd.
+ * Change the fd for this device, without re-reading the actual device. If the fd
+ * changes after initializing the device, for example after a VT-switch in the
+ * X.org X server, this function updates the internal fd to the newly opened.
+ * No check is made that new fd points to the same device. If the device has
+ * changed, libevdev's behavior is undefined.
+ *
+ * The fd may be open in O_RDONLY or O_RDWR.
+ *
+ * It is an error to call this function before calling libevdev_set_fd().
  *
  * @param fd The new fd
  *
@@ -149,6 +256,8 @@ int libevdev_change_fd(struct libevdev* dev, int fd);
 int libevdev_get_fd(const struct libevdev* dev);
 
 /**
+ * @ingroup events
+ *
  * Get the next event from the device.
  *
  * In normal mode, this function returns 0 and returns the event in the
@@ -176,6 +285,8 @@ int libevdev_get_fd(const struct libevdev* dev);
 int libevdev_next_event(struct libevdev *dev, unsigned int flags, struct input_event *ev);
 
 /**
+ * @ingroup bits
+ *
  * @return The device name as read off the kernel device
  *
  * @note This function is signal-safe.
@@ -183,6 +294,8 @@ int libevdev_next_event(struct libevdev *dev, unsigned int flags, struct input_e
 const char* libevdev_get_name(const struct libevdev *dev);
 
 /**
+ * @ingroup bits
+ *
  * Virtual devices such as uinput devices have no phys location.
  *
  * @return The physical location of this device, or NULL if there is none
@@ -192,6 +305,8 @@ const char* libevdev_get_name(const struct libevdev *dev);
 const char * libevdev_get_phys(const struct libevdev *dev);
 
 /**
+ * @ingroup bits
+ *
  * @return The unique identifier for this device, or NULL if there is none
  *
  * @note This function is signal safe.
@@ -199,12 +314,17 @@ const char * libevdev_get_phys(const struct libevdev *dev);
 const char * libevdev_get_uniq(const struct libevdev *dev);
 
 /**
+ * @ingroup bits
+ *
  * @return The device's product ID
  *
  * @note This function is signal-safe.
  */
 int libevdev_get_product_id(const struct libevdev *dev);
+
 /**
+ * @ingroup bits
+ *
  * @return The device's vendor ID
  *
  * @note This function is signal-safe.
@@ -212,6 +332,8 @@ int libevdev_get_product_id(const struct libevdev *dev);
 int libevdev_get_vendor_id(const struct libevdev *dev);
 
 /**
+ * @ingroup bits
+ *
  * @return The device's bus type
  *
  * @note This function is signal-safe.
@@ -219,6 +341,8 @@ int libevdev_get_vendor_id(const struct libevdev *dev);
 int libevdev_get_bustype(const struct libevdev *dev);
 
 /**
+ * @ingroup bits
+ *
  * @return The device's firmware version
  *
  * @note This function is signal-safe.
@@ -226,6 +350,8 @@ int libevdev_get_bustype(const struct libevdev *dev);
 int libevdev_get_version(const struct libevdev *dev);
 
 /**
+ * @ingroup bits
+ *
  * @return The driver version for this device
  *
  * @note This function is signal-safe.
@@ -233,6 +359,8 @@ int libevdev_get_version(const struct libevdev *dev);
 int libevdev_get_driver_version(const struct libevdev *dev);
 
 /**
+ * @ingroup bits
+ *
  * @return 1 if the device supports this event type, or 0 otherwise.
  *
  * @note This function is signal-safe
@@ -240,6 +368,8 @@ int libevdev_get_driver_version(const struct libevdev *dev);
 int libevdev_has_property(const struct libevdev *dev, unsigned int prop);
 
 /**
+ * @ingroup bits
+ *
  * @return 1 if the device supports this event type, or 0 otherwise.
  *
  * @note This function is signal-safe.
@@ -247,6 +377,8 @@ int libevdev_has_property(const struct libevdev *dev, unsigned int prop);
 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.
  *
  * @note This function is signal-safe.
@@ -254,33 +386,47 @@ int libevdev_has_event_type(const struct libevdev *dev, unsigned int type);
 int libevdev_has_event_code(const struct libevdev *dev, unsigned int type, unsigned int code);
 
 /**
+ * @ingroup bits
+ *
  * @return axis minimum for the given axis or 0 if the axis is invalid
  */
 int libevdev_get_abs_min(const struct libevdev *dev, unsigned int code);
 /**
+ * @ingroup bits
+ *
  * @return axis maximum for the given axis or 0 if the axis is invalid
  */
 int libevdev_get_abs_max(const struct libevdev *dev, unsigned int code);
 /**
+ * @ingroup bits
+ *
  * @return axis fuzz for the given axis or 0 if the axis is invalid
  */
 int libevdev_get_abs_fuzz(const struct libevdev *dev, unsigned int code);
 /**
+ * @ingroup bits
+ *
  * @return axis flat for the given axis or 0 if the axis is invalid
  */
 int libevdev_get_abs_flat(const struct libevdev *dev, unsigned int code);
 /**
+ * @ingroup bits
+ *
  * @return axis resolution for the given axis or 0 if the axis is invalid
  */
 int libevdev_get_abs_resolution(const struct libevdev *dev, unsigned int code);
 
 /**
+ * @ingroup bits
+ *
  * @return The input_absinfo for the given code, or NULL if the device does
  * not support this event code.
  */
 const struct input_absinfo* libevdev_get_abs_info(const struct libevdev *dev, unsigned int code);
 
 /**
+ * @ingroup bits
+ *
  * Behaviour of this function is undefined if the device does not provide
  * the event.
  *
@@ -295,6 +441,8 @@ const struct input_absinfo* libevdev_get_abs_info(const struct libevdev *dev, un
 int libevdev_get_event_value(const struct libevdev *dev, unsigned int type, unsigned int code);
 
 /**
+ * @ingroup bits
+ *
  * Fetch the current value of the event type. This is a shortcut for
  *
  * <pre>
@@ -314,6 +462,8 @@ int libevdev_get_event_value(const struct libevdev *dev, unsigned int type, unsi
 int libevdev_fetch_event_value(const struct libevdev *dev, unsigned int type, unsigned int code, int *value);
 
 /**
+ * @ingroup mt
+ *
  * Return the current value of the code for the given slot.
  *
  * The return value is undefined for a slot exceeding the available slots on
@@ -328,6 +478,8 @@ int libevdev_fetch_event_value(const struct libevdev *dev, unsigned int type, un
 int libevdev_get_slot_value(const struct libevdev *dev, unsigned int slot, unsigned int code);
 
 /**
+ * @ingroup mt
+ *
  * Fetch the current value of the code for the given slot. This is a shortcut for
  *
  * <pre>
@@ -349,6 +501,8 @@ int libevdev_get_slot_value(const struct libevdev *dev, unsigned int slot, unsig
 int libevdev_fetch_slot_value(const struct libevdev *dev, unsigned int slot, unsigned int code, int *value);
 
 /**
+ * @ingroup mt
+ *
  * Get the number of slots supported by this device.
  *
  * Note that the slot offset may be non-zero, use libevdev_get_abs_min() or
@@ -359,6 +513,8 @@ int libevdev_fetch_slot_value(const struct libevdev *dev, unsigned int slot, uns
 int libevdev_get_num_slots(const struct libevdev *dev);
 
 /**
+ * @ingroup mt
+ *
  * Get the currently active slot. This may differ from the value
  * an ioctl may return at this time as events may have been read off the fd
  * since changing the slot value but those events are still in the buffer
@@ -370,6 +526,8 @@ int libevdev_get_num_slots(const struct libevdev *dev);
 int libevdev_get_current_slot(const struct libevdev *dev);
 
 /**
+ * @ingroup kernel
+ *
  * 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.
@@ -386,6 +544,8 @@ int libevdev_get_current_slot(const struct libevdev *dev);
 int libevdev_enable_event_type(struct libevdev *dev, unsigned int type);
 
 /**
+ * @ingroup kernel
+ *
  * 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.
@@ -407,6 +567,8 @@ int libevdev_enable_event_type(struct libevdev *dev, unsigned int type);
 int libevdev_disable_event_type(struct libevdev *dev, unsigned int type);
 
 /**
+ * @ingroup kernel
+ *
  * 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.
@@ -432,6 +594,8 @@ int libevdev_disable_event_type(struct libevdev *dev, unsigned int type);
 int libevdev_enable_event_code(struct libevdev *dev, unsigned int type, unsigned int code, const void *data);
 
 /**
+ * @ingroup kernel
+ *
  * Forcibly disable an event code on this device, even if the underlying
  * device provides it, effectively muting this key or axis. libevdev will
  * filter any events matching this type and code and none will reach the
@@ -456,6 +620,8 @@ int libevdev_disable_event_code(struct libevdev *dev, unsigned int type, unsigne
 
 
 /**
+ * @ingroup kernel
+ *
  * 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.
@@ -473,6 +639,8 @@ int libevdev_disable_event_code(struct libevdev *dev, unsigned int type, unsigne
 int libevdev_kernel_enable_event_type(struct libevdev *dev, unsigned int type);
 
 /**
+ * @ingroup kernel
+ *
  * 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.
@@ -490,6 +658,8 @@ int libevdev_kernel_enable_event_type(struct libevdev *dev, unsigned int type);
 int libevdev_kernel_enable_event_code(struct libevdev *dev, unsigned int type, unsigned int code);
 
 /**
+ * @ingroup kernel
+ *
  * Set the device's EV_ABS axis to the value defined in the abs
  * parameter. This will be written to the kernel.
  *
@@ -500,6 +670,8 @@ int libevdev_kernel_enable_event_code(struct libevdev *dev, unsigned int type, u
 int libevdev_kernel_set_abs_value(struct libevdev *dev, unsigned int code, const struct input_absinfo *abs);
 
 /**
+ * @ingroup misc
+ *
  * @return The name of the given event type (e.g. EV_ABS) or NULL for an
  * invalid type
  *
@@ -508,6 +680,8 @@ int libevdev_kernel_set_abs_value(struct libevdev *dev, unsigned int code, const
  */
 const char * libevdev_get_event_type_name(unsigned int type);
 /**
+ * @ingroup misc
+ *
  * @return The name of the given event code (e.g. ABS_X) or NULL for an
  * invalid type or code
  *
@@ -517,6 +691,8 @@ const char * libevdev_get_event_type_name(unsigned int type);
 const char * libevdev_get_event_code_name(unsigned int type, unsigned int code);
 
 /**
+ * @ingroup misc
+ *
  * @return The name of the given input prop (e.g. INPUT_PROP_BUTTONPAD) or NULL for an
  * invalid property
  *
@@ -528,6 +704,8 @@ const char * libevdev_get_event_code_name(unsigned int type, unsigned int code);
 const char * libevdev_get_input_prop_name(unsigned int prop);
 
 /**
+ * @ingroup misc
+ *
  * @return The max value defined for the given event type, e.g. ABS_MAX for a type of EV_ABS, or -1
  * for an invalid type.
  *
@@ -537,6 +715,8 @@ const char * libevdev_get_input_prop_name(unsigned int prop);
 int libevdev_get_event_type_max(unsigned int type);
 
 /**
+ * @ingroup bits
+ *
  * Get the repeat delay and repeat period values for this device.
  *
  * @param delay If not null, set to the repeat delay value