Documentation updates

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

src/libei.h

@@ -391,8 +391,8 @@ ei_property_set(struct ei *ei, const char *property, const char *value);
  * @retval -EPERM The permissions mask is too loose
  */
 int
-ei_property_set_with_permissions(struct ei *ei, const char *property, const char *value,
-				 uint32_t permission);
+ei_property_set_with_permissions(struct ei *ei, const char *property,
+				 const char *value, uint32_t permission);
 
 /**
  * Return the permissions mask for the given property. If the property does
@@ -991,9 +991,31 @@ ei_keymap_get_context(struct ei_keymap *keymap);
 struct ei *
 ei_device_get_context(struct ei_device *device);
 
+/**
+ * Notify the EIS implementation that the given device is about to start
+ * sending events. This should be seen more as a transactional boundary than a
+ * time-based boundary. The primary use-case for this is to allow for setup on
+ * the EIS implementation side and/or UI updates to indicate that a device is
+ * sending events now.
+ *
+ * There is no actual requirement that events start immediately once emulation
+ * starts and there is no requirement that a client calls
+ * ei_device_stop_emulating() after the most recent events.
+ *
+ * For example, in a synergy-like use-case the client would call
+ * ei_device_start_emulating() once the pointer moves into the the screen and
+ * ei_device_stop_emulating() once the pointer moves out of the screen.
+ *
+ * Sending events before ei_device_start_emulating() or after
+ * ei_device_stop_emulating() is a client bug.
+ */
 void
 ei_device_start_emulating(struct ei_device *device);
 
+/**
+ * Notify the EIS implementation that the given device is no longer sending
+ * events. See ei_device_start_emulating() for details.
+ */
 void
 ei_device_stop_emulating(struct ei_device *device);
 
@@ -1020,10 +1042,8 @@ ei_device_pointer_motion(struct ei_device *device, double x, double y);
  * Generate an absolute motion event on a device with
  * the @ref EI_DEVICE_CAP_POINTER_ABSOLUTE capability.
  *
- * The required conditions are:
- * - 0 <= x < width
- * - 0 <= y < height
- * If these conditions are not met, the event is silently discarded.
+ * The x/y coordinate must be within the device's regions or the event is
+ * silently discarded.
  *
  * @param device The EI device
  * @param x The x position in logical pixels
@@ -1049,7 +1069,7 @@ ei_device_pointer_button(struct ei_device *device,
 			 uint32_t button, bool is_press);
 
 /**
- * Generate a scroll event on a device with
+ * Generate a smooth (pixel-precise) scroll event on a device with
  * the @ref EI_DEVICE_CAP_POINTER_ABSOLUTE or
  * @ref EI_DEVICE_CAP_POINTER capability.
  *
@@ -1150,6 +1170,11 @@ ei_device_pointer_scroll_cancel(struct ei_device *device, bool cancel_x, bool ca
  * Keys use the evdev scan codes as defined in
  * linux/input-event-codes.h
  *
+ * Note that this is a keymap-independent key code, equivalent to the scancode
+ * a physical keyboard would produce. To generate a specific key symbol, a
+ * client must look at the keymap returned by ei_device_get_keymap() and
+ * generate the appropriate keycodes.
+ *
  * @param device The EI device
  * @param keycode The key code
  * @param is_press true for key down, false for key up
@@ -1263,9 +1288,9 @@ ei_event_property_get_name(struct ei_event *event);
  * A property value of NULL indicates the property has been deleted.
  *
  * Note that the property value as seen in the event and the property value on
- * the ei context itself may differ. The latter always reflects the current
- * state of the property while the event contains the value of the property
- * at the time of the event.
+ * the ei context as returned by ei_property_get() may differ. The latter
+ * always reflects the current state of the property while the event contains
+ * the value of the property at the time of the event.
  */
 const char *
 ei_event_property_get_value(struct ei_event *event);
@@ -1275,9 +1300,10 @@ ei_event_property_get_value(struct ei_event *event);
  * property (at the time of the event).
  *
  * Note that the property permissions as seen in the event and the property
- * permissiosn on the ei context itself may differ. The latter always reflects
- * the current state of the property while the event contains the permissions of
- * the property at the time of the event.
+ * permissiosn on the ei context as returned by ei_property_get_permissions()
+ * may differ. The latter always reflects the current state of the property
+ * while the event contains the permissions of the property at the time of the
+ * event.
  */
 uint32_t
 ei_event_property_get_permissions(struct ei_event *event);