A whole bunch of documentation updates/improvements

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

doc/device-configuration-via-udev.dox

@@ -11,7 +11,22 @@ The following udev properties are supported:
 <dt>LIBINPUT_CALIBRATION_MATRIX</dt>
 <dd>Sets the calibration matrix, see
 libinput_device_config_calibration_get_default_matrix(). If unset,
-defaults to the identity matrix.</dd>
+defaults to the identity matrix.
+
+The udev property is parsed as 6 floating point numbers separated by a
+single space each (scanf(3) format "%f %f %f %f %f %f").
+The 6 values represent the first two rows of the calibration matrix as
+described in libinput_device_config_calibration_set_matrix().
+
+Example values are:
+@code
+ ENV{LIBINPUT_CALIBRATION_MATRIX}="1 0 0 0 1 0" # default
+ ENV{LIBINPUT_CALIBRATION_MATRIX}="0 -1 1 1 0 0" # 90 degree clockwise
+ ENV{LIBINPUT_CALIBRATION_MATRIX}="-1 0 1 0 -1 1" # 180 degree clockwise
+ ENV{LIBINPUT_CALIBRATION_MATRIX}="0 1 0 -1 0 1" # 270 degree clockwise
+ ENV{LIBINPUT_CALIBRATION_MATRIX}="-1 0 1 1 0 0" # reflect along y axis
+@endcode
+</dd>
 <dt>LIBINPUT_DEVICE_GROUP</dt>
 <dd>A string identifying the @ref libinput_device_group for this device. Two
 devices with the same property value are grouped into the same device group,

src/libinput.h

@@ -48,8 +48,7 @@ enum libinput_log_priority {
  * @ingroup device
  *
  * Capabilities on a device. A device may have one or more capabilities
- * at a time, and capabilities may appear or disappear during the
+ * at a time, capabilities remain static for the lifetime of the device.
- * lifetime of the device.
  */
 enum libinput_device_capability {
 	LIBINPUT_DEVICE_CAP_KEYBOARD = 0,
@@ -93,7 +92,8 @@ enum libinput_button_state {
 /**
  * @ingroup device
  *
- * Axes on a device that are not x or y coordinates.
+ * Axes on a device with the capability @ref LIBINPUT_DEVICE_CAP_POINTER
+ * that are not x or y coordinates.
  *
  * The two scroll axes @ref LIBINPUT_POINTER_AXIS_SCROLL_VERTICAL and
  * @ref LIBINPUT_POINTER_AXIS_SCROLL_HORIZONTAL are engaged separately,
@@ -304,9 +304,9 @@ libinput_event_get_context(struct libinput_event *event);
 /**
  * @ingroup event
  *
- * Return the device associated with this event, if applicable. For device
+ * Return the device associated with this event. For device added/removed
- * added/removed events this is the device added or removed. For all other
+ * events this is the device added or removed. For all other device events,
- * device events, this is the device that generated the event.
+ * this is the device that generated the event.
  *
  * This device is not refcounted and its lifetime is that of the event. Use
  * libinput_device_ref() before using the device outside of this scope.
@@ -424,7 +424,7 @@ libinput_event_keyboard_get_base_event(struct libinput_event_keyboard *event);
  * of keys pressed on all devices on the associated seat after the event was
  * triggered.
  *
- " @note It is an application bug to call this function for events other than
+ * @note It is an application bug to call this function for events other than
  * @ref LIBINPUT_EVENT_KEYBOARD_KEY. For other events, this function returns 0.
  *
  * @return the seat wide pressed key count for the key of this event
@@ -649,7 +649,7 @@ libinput_event_pointer_get_button_state(struct libinput_event_pointer *event);
  * total number of buttons pressed on all devices on the associated seat
  * after the event was triggered.
  *
- " @note It is an application bug to call this function for events other than
+ * @note It is an application bug to call this function for events other than
  * @ref LIBINPUT_EVENT_POINTER_BUTTON. For other events, this function
  * returns 0.
  *
@@ -1059,7 +1059,11 @@ libinput_get_fd(struct libinput *libinput);
  * and processes them internally. Use libinput_get_event() to retrieve the
  * events.
  *
- * Dispatching does not necessarily queue libinput events.
+ * Dispatching does not necessarily queue libinput events. This function
+ * should be called immediately once data is available on the file
+ * descriptor returned by libinput_get_fd(). libinput has a number of
+ * timing-sensitive features (e.g. tap-to-click), any delay in calling
+ * libinput_dispatch() may prevent these features from working correctly.
  *
  * @param libinput A previously initialized libinput context
  *
@@ -1090,8 +1094,8 @@ libinput_get_event(struct libinput *libinput);
  * libinput_get_event() returns that event.
  *
  * @param libinput A previously initialized libinput context
- * @return The event type of the next available event or LIBINPUT_EVENT_NONE
+ * @return The event type of the next available event or @ref
- * if no event is availble.
+ * LIBINPUT_EVENT_NONE if no event is availble.
  */
 enum libinput_event_type
 libinput_next_event_type(struct libinput *libinput);
@@ -1099,6 +1103,10 @@ libinput_next_event_type(struct libinput *libinput);
 /**
  * @ingroup base
  *
+ * Set caller-specific data associated with this context. libinput does
+ * not manage, look at, or modify this data. The caller must ensure the
+ * data is valid.
+ *
  * @param libinput A previously initialized libinput context
  * @param user_data Caller-specific data passed to the various callback
  * interfaces.
@@ -1110,6 +1118,8 @@ libinput_set_user_data(struct libinput *libinput,
 /**
  * @ingroup base
  *
+ * Get the caller-specific data associated with this context, if any.
+ *
  * @param libinput A previously initialized libinput context
  * @return the caller-specific data previously assigned in
  * libinput_create_udev().
@@ -1171,10 +1181,11 @@ libinput_unref(struct libinput *libinput);
 /**
  * @ingroup base
  *
- * Set the global log priority. Messages with priorities equal to or
+ * Set the log priority for the libinput context. Messages with priorities
- * higher than the argument will be printed to the current log handler.
+ * equal to or higher than the argument will be printed to the context's
+ * log handler.
  *
- * The default log priority is LIBINPUT_LOG_PRIORITY_ERROR.
+ * The default log priority is @ref LIBINPUT_LOG_PRIORITY_ERROR.
  *
  * @param libinput A previously initialized libinput context
  * @param priority The minimum priority of log messages to print.
@@ -1189,10 +1200,10 @@ libinput_log_set_priority(struct libinput *libinput,
 /**
  * @ingroup base
  *
- * Get the global log priority. Messages with priorities equal to or
+ * Get the context's log priority. Messages with priorities equal to or
  * higher than the argument will be printed to the current log handler.
  *
- * The default log priority is LIBINPUT_LOG_PRIORITY_ERROR.
+ * The default log priority is @ref LIBINPUT_LOG_PRIORITY_ERROR.
  *
  * @param libinput A previously initialized libinput context
  * @return The minimum priority of log messages to print.
@@ -1225,8 +1236,8 @@ typedef void (*libinput_log_handler)(struct libinput *libinput,
 /**
  * @ingroup base
  *
- * Set the global log handler. Messages with priorities equal to or higher
+ * Set the context's log handler. Messages with priorities equal to or
- * than the current log priority will be passed to the given
+ * higher than the context's log priority will be passed to the given
  * log handler.
  *
  * The default log handler prints to stderr.
@@ -1254,7 +1265,7 @@ libinput_log_set_handler(struct libinput *libinput,
  * @ingroup seat
  *
  * Increase the refcount of the seat. A seat will be freed whenever the
- * refcount reaches 0. This may happen during dispatch if the
+ * refcount reaches 0. This may happen during libinput_dispatch() if the
  * seat was removed from the system. A caller must ensure to reference
  * the seat correctly to avoid dangling pointers.
  *
@@ -1268,7 +1279,7 @@ libinput_seat_ref(struct libinput_seat *seat);
  * @ingroup seat
  *
  * Decrease the refcount of the seat. A seat will be freed whenever the
- * refcount reaches 0. This may happen during dispatch if the
+ * refcount reaches 0. This may happen during libinput_dispatch() if the
  * seat was removed from the system. A caller must ensure to reference
  * the seat correctly to avoid dangling pointers.
  *
@@ -1354,9 +1365,9 @@ libinput_seat_get_logical_name(struct libinput_seat *seat);
  * @ingroup device
  *
  * Increase the refcount of the input device. An input device will be freed
- * whenever the refcount reaches 0. This may happen during dispatch if the
+ * whenever the refcount reaches 0. This may happen during
- * device was removed from the system. A caller must ensure to reference
+ * libinput_dispatch() if the device was removed from the system. A caller
- * the device correctly to avoid dangling pointers.
+ * must ensure to reference the device correctly to avoid dangling pointers.
  *
  * @param device A previously obtained device
  * @return The passed device
@@ -1368,9 +1379,9 @@ libinput_device_ref(struct libinput_device *device);
  * @ingroup device
  *
  * Decrease the refcount of the input device. An input device will be freed
- * whenever the refcount reaches 0. This may happen during dispatch if the
+ * whenever the refcount reaches 0. This may happen during libinput_dispatch
- * device was removed from the system. A caller must ensure to reference
+ * if the device was removed from the system. A caller must ensure to
- * the device correctly to avoid dangling pointers.
+ * reference the device correctly to avoid dangling pointers.
  *
  * @param device A previously obtained device
  * @return NULL if the device was destroyed, otherwise the passed device
@@ -1547,7 +1558,8 @@ libinput_device_get_output_name(struct libinput_device *device);
 /**
  * @ingroup device
  *
- * Get the seat associated with this input device.
+ * Get the seat associated with this input device, see @ref seats for
+ * details.
  *
  * A seat can be uniquely identified by the physical and logical seat name.
  * There will ever be only one seat instance with a given physical and logical
@@ -1567,10 +1579,13 @@ libinput_device_get_seat(struct libinput_device *device);
  * device and adding it to the new seat.
  *
  * This command is identical to physically unplugging the device, then
- * re-plugging it as member of the new seat,
+ * re-plugging it as member of the new seat. libinput will generate a
- * @ref LIBINPUT_EVENT_DEVICE_REMOVED and @ref LIBINPUT_EVENT_DEVICE_ADDED
+ * @ref LIBINPUT_EVENT_DEVICE_REMOVED event and this @ref libinput_device is
- * events are sent accordingly. Those events mark the end of the lifetime
+ * considered removed from the context; it will not generate further events
- * of this device and the start of a new device.
+ * and will be freed when the refcount reaches zero.
+ * A @ref LIBINPUT_EVENT_DEVICE_ADDED event is generated with a new @ref
+ * libinput_device handle. It is the caller's responsibility to update
+ * references to the new device accordingly.
  *
  * If the logical seat name already exists in the device's physical seat,
  * the device is added to this seat. Otherwise, a new seat is created.
@@ -1591,7 +1606,9 @@ libinput_device_set_seat_logical_name(struct libinput_device *device,
  *
  * Return a udev handle to the device that is this libinput device, if any.
  * The returned handle has a refcount of at least 1, the caller must call
- * udev_device_unref() once to release the associated resources.
+ * <i>udev_device_unref()</i> once to release the associated resources.
+ * See the [libudev documentation]
+ * (http://www.freedesktop.org/software/systemd/libudev/) for details.
  *
  * Some devices may not have a udev device, or the udev device may be
  * unobtainable. This function returns NULL if no udev device was available.
@@ -1625,7 +1642,7 @@ libinput_device_led_update(struct libinput_device *device,
  *
  * Check if the given device has the specified capability
  *
- * @return 1 if the given device has the capability or 0 if not
+ * @return Non-zero if the given device has the capability or zero otherwise
  */
 int
 libinput_device_has_capability(struct libinput_device *device,
@@ -1654,10 +1671,10 @@ libinput_device_get_size(struct libinput_device *device,
  * @ingroup device
  *
  * Check if a @ref LIBINPUT_DEVICE_CAP_POINTER device has a button with the
- * passed in code (see linux/input.h).
+ * given code (see linux/input.h).
  *
  * @param device A current input device
- * @param code button code to check for
+ * @param code Button code to check for, e.g. <i>BTN_LEFT</i>
  *
  * @return 1 if the device supports this button code, 0 if it does not, -1
  * on error.
@@ -1677,9 +1694,10 @@ libinput_device_has_button(struct libinput_device *device, uint32_t code) LIBINP
  * @ingroup device
  *
  * Increase the refcount of the device group. A device group will be freed
- * whenever the refcount reaches 0. This may happen during dispatch if all
+ * whenever the refcount reaches 0. This may happen during
- * devices of this group were removed from the system. A caller must ensure
+ * libinput_dispatch() if all devices of this group were removed from the
- * to reference the device group correctly to avoid dangling pointers.
+ * system. A caller must ensure to reference the device group correctly to
+ * avoid dangling pointers.
  *
  * @param group A previously obtained device group
  * @return The passed device group
@@ -1691,9 +1709,10 @@ libinput_device_group_ref(struct libinput_device_group *group);
  * @ingroup device
  *
  * Decrease the refcount of the device group. A device group will be freed
- * whenever the refcount reaches 0. This may happen during dispatch if all
+ * whenever the refcount reaches 0. This may happen during
- * devices of this group were removed from the system. A caller must ensure
+ * libinput_dispatch() if all devices of this group were removed from the
- * to reference the device group correctly to avoid dangling pointers.
+ * system. A caller must ensure to reference the device group correctly to
+ * avoid dangling pointers.
  *
  * @param group A previously obtained device group
  * @return NULL if the device group was destroyed, otherwise the passed
@@ -1740,7 +1759,7 @@ libinput_device_group_get_user_data(struct libinput_device_group *group);
  *
  * Some configuration option may be dependent on or mutually exclusive with
  * with other options. The behavior in those cases is
- * implementation-defined, the caller must ensure that the options are set
+ * implementation-dependent, the caller must ensure that the options are set
  * in the right order.
  */
 
@@ -1781,7 +1800,8 @@ enum libinput_config_tap_state {
 /**
  * @ingroup config
  *
- * Check if the device supports tap-to-click. See
+ * Check if the device supports tap-to-click and how many fingers can be
+ * used for tapping. See
  * libinput_device_config_tap_set_enabled() for more information.
  *
  * @param device The device to configure
@@ -1827,8 +1847,8 @@ libinput_device_config_tap_set_enabled(struct libinput_device *device,
  *
  * @param device The device to configure
  *
- * @return @ref LIBINPUT_CONFIG_TAP_ENABLED if tapping is currently enabled,
+ * @retval LIBINPUT_CONFIG_TAP_ENABLED If tapping is currently enabled
- * or @ref LIBINPUT_CONFIG_TAP_DISABLED is currently disabled
+ * @retval LIBINPUT_CONFIG_TAP_DISABLED If tapping is currently disabled
  *
  * @see libinput_device_config_tap_get_finger_count
  * @see libinput_device_config_tap_set_enabled
@@ -1840,11 +1860,12 @@ libinput_device_config_tap_get_enabled(struct libinput_device *device);
 /**
  * @ingroup config
  *
- * Return the default setting for whether tapping is enabled on this device.
+ * Return the default setting for whether tap-to-click is enabled on this
+ * device.
  *
  * @param device The device to configure
- * @return @ref LIBINPUT_CONFIG_TAP_ENABLED if tapping is enabled by default,
+ * @retval LIBINPUT_CONFIG_TAP_ENABLED If tapping is enabled by default
- * or @ref LIBINPUT_CONFIG_TAP_DISABLED is disabled by default
+ * @retval LIBINPUT_CONFIG_TAP_DISABLED If tapping Is disabled by default
  *
  * @see libinput_device_config_tap_get_finger_count
  * @see libinput_device_config_tap_set_enabled
@@ -1947,21 +1968,7 @@ libinput_device_config_calibration_get_matrix(struct libinput_device *device,
  * Return the default calibration matrix for this device. On most devices,
  * this is the identity matrix. If the udev property
  * <b>LIBINPUT_CALIBRATION_MATRIX</b> is set on the respective udev device,
- * that property's value becomes the default matrix.
+ * that property's value becomes the default matrix, see @ref udev_config.
- *
- * The udev property is parsed as 6 floating point numbers separated by a
- * single space each (scanf(3) format "%f %f %f %f %f %f").
- * The 6 values represent the first two rows of the calibration matrix as
- * described in libinput_device_config_calibration_set_matrix().
- *
- * Example values are:
- * @code
- * ENV{LIBINPUT_CALIBRATION_MATRIX}="1 0 0 0 1 0" # default
- * ENV{LIBINPUT_CALIBRATION_MATRIX}="0 -1 1 1 0 0" # 90 degree clockwise
- * ENV{LIBINPUT_CALIBRATION_MATRIX}="-1 0 1 0 -1 1" # 180 degree clockwise
- * ENV{LIBINPUT_CALIBRATION_MATRIX}="0 1 0 -1 0 1" # 270 degree clockwise
- * ENV{LIBINPUT_CALIBRATION_MATRIX}="-1 0 1 1 0 0" # reflect along y axis
- * @endcode
  *
  * @param device The device to configure
  * @param matrix Set to the array representing the first two rows of a 3x3 matrix as
@@ -2179,7 +2186,7 @@ libinput_device_config_accel_get_default_speed(struct libinput_device *device);
  *
  * @param device The device to configure
  *
- * @return 0 if natural scrolling is not supported, non-zero if natural
+ * @return Zero if natural scrolling is not supported, non-zero if natural
  * scrolling is supported by this device
  *
  * @see libinput_device_config_set_natural_scroll_enabled
@@ -2257,9 +2264,7 @@ libinput_device_config_left_handed_is_available(struct libinput_device *device);
 /**
  * @ingroup config
  *
- * Set the left-handed configuration of the device. For example, a pointing
+ * Set the left-handed configuration of the device.
- * device may reverse it's buttons and send a right button click when the
- * left button is pressed, and vice versa.
  *
  * The exact behavior is device-dependent. On a mouse and most pointing
  * devices, left and right buttons are swapped but the middle button is
@@ -2325,7 +2330,7 @@ libinput_device_config_left_handed_get_default(struct libinput_device *device);
 enum libinput_config_click_method {
 	/**
 	 * Do not send software-emulated button events. This has no effect
-	 * on physical button generations.
+	 * on events generated by physical buttons.
 	 */
 	LIBINPUT_CONFIG_CLICK_METHOD_NONE = 0,
 	/**
@@ -2425,15 +2430,16 @@ libinput_device_config_click_get_default_method(struct libinput_device *device);
 enum libinput_config_scroll_method {
 	/**
 	 * Never send scroll events instead of pointer motion events.
-	 * Note scroll wheels, etc. will still send scroll events.
+	 * This has no effect on events generated by scroll wheels.
 	 */
 	LIBINPUT_CONFIG_SCROLL_NO_SCROLL = 0,
 	/**
-	 * Send scroll events when 2 fingers are down on the device.
+	 * Send scroll events when two fingers are logically down on the
+	 * device.
 	 */
 	LIBINPUT_CONFIG_SCROLL_2FG = (1 << 0),
 	/**
-	 * Send scroll events when a finger is moved along the bottom or
+	 * Send scroll events when a finger moves along the bottom or
 	 * right edge of a device.
 	 */
 	LIBINPUT_CONFIG_SCROLL_EDGE = (1 << 1),
@@ -2552,9 +2558,10 @@ libinput_device_config_scroll_get_default_method(struct libinput_device *device)
  * @param button The button which when pressed switches to sending scroll events
  *
  * @return a config status code
- * @retval LIBINPUT_CONFIG_STATUS_SUCCESS on success
+ * @retval LIBINPUT_CONFIG_STATUS_SUCCESS On success
- * @retval LIBINPUT_CONFIG_STATUS_UNSUPPORTED if @ref LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN is not supported
+ * @retval LIBINPUT_CONFIG_STATUS_UNSUPPORTED If @ref
- * @retval LIBINPUT_CONFIG_STATUS_INVALID the given button does not
+ * LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN is not supported
+ * @retval LIBINPUT_CONFIG_STATUS_INVALID The given button does not
  * exist on this device
  *
  * @see libinput_device_config_scroll_get_methods
@@ -2571,11 +2578,11 @@ libinput_device_config_scroll_set_button(struct libinput_device *device,
 /**
  * @ingroup config
  *
- * Get the button for the @ref LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN method for
+ * Get the button for the @ref LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN method
- * this device.
+ * for this device.
  *
- * If @ref LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN scroll method is not supported,
+ * If @ref LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN scroll method is not
- * or no button is set, this function returns 0.
+ * supported, or no button is set, this function returns 0.
  *
  * @note The return value is independent of the currently selected
  * scroll-method. For button scrolling to activate, a device must have the
@@ -2598,14 +2605,15 @@ libinput_device_config_scroll_get_button(struct libinput_device *device);
 /**
  * @ingroup config
  *
- * Get the default button for LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN method
+ * Get the default button for the @ref LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN
- * for this device.
+ * method for this device.
  *
  * If @ref LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN scroll method is not supported,
  * or no default button is set, this function returns 0.
  *
  * @param device The device to configure
- * @return The default button for LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN method
+ * @return The default button for the @ref
+ * LIBINPUT_CONFIG_SCROLL_ON_BUTTON_DOWN method
  *
  * @see libinput_device_config_scroll_get_methods
  * @see libinput_device_config_scroll_set_method