libei: some more documentation

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

src/libei.h

@@ -584,13 +584,15 @@ ei_event_get_type(struct ei_event *event);
 /**
  * Return the device from this event.
  *
+ * For events of type @ref EI_EVENT_CONNECT and @ref EI_EVENT_DISCONNECT,
+ * this function returns NULL.
+ *
  * This does not increase the refcount of the device. Use eis_device_ref()
  * to keep a reference beyond the immediate scope.
  */
 struct ei_device *
 ei_event_get_device(struct ei_event *event);
 
-
 /**
  * @return the event time in microseconds
  */

src/libeis.h

@@ -133,9 +133,24 @@ eis_setup_backend_fd(struct eis *ctx);
 int
 eis_backend_fd_add_fd(struct eis *ctx, int fd);
 
+/**
+ * libeis keeps a single file descriptor for all events. This fd should be
+ * monitored for events by the caller's mainloop, e.g. using select(). When
+ * events are available on this fd, call libeis_dispatch() immediately to
+ * process.
+ */
 int
 eis_get_fd(struct eis *eis);
 
+/**
+ * Main event dispatchment function. Reads events of the file descriptors
+ * and processes them internally. Use libeis_get_event() to retrieve the
+ * events.
+ *
+ * Dispatching does not necessarily queue events. This function
+ * should be called immediately once data is available on the file
+ * descriptor returned by libeis_get_fd().
+ */
 void
 eis_dispatch(struct eis *eis);
 
@@ -171,6 +186,15 @@ eis_get_event(struct eis *eis);
 struct eis_event *
 eis_peek_event(struct eis *eis);
 
+/**
+ * Release resources associated with this event. This function always
+ * returns NULL.
+ *
+ * The caller cannot increase the refcount of an event. Events should be
+ * considered transient data and not be held longer than required.
+ * eis_event_unref() is provided for consistency (as opposed to, say,
+ * eis_event_free()).
+ */
 struct eis_event *
 eis_event_unref(struct eis_event *event);
 
@@ -180,6 +204,10 @@ eis_client_ref(struct eis_client *client);
 struct eis_client *
 eis_client_unref(struct eis_client *client);
 
+/**
+ * Return the name set by this client. The server is under no obligation to
+ * use this name.
+ */
 const char *
 eis_client_get_name(struct eis_client *client);
 
@@ -221,6 +249,11 @@ eis_device_ref(struct eis_device *device);
 struct eis_device *
 eis_device_unref(struct eis_device *device);
 
+/**
+ * Return the name of the device. The return value of this function may change after
+ * eis_device_set_name(), a caller should keep a copy of it where required rather than the
+ * pointer value.
+ */
 const char *
 eis_device_get_name(struct eis_device *device);
 
@@ -296,14 +329,11 @@ void
 eis_device_resume(struct eis_device *device);
 
 /**
- * Get the width of the absolute pointer device in 1/1000th of a logical
- * pixel. The allowable range for absolute pointer motion is
+ * Get the width of the absolute pointer device in logical
+ * pixels. The allowable range for absolute pointer motion is
  * [0, max) for each axis, i.e. zero inclusive, max exclusive. Coordinates
  * outside this range may be discarded or clipped silently by the library.
  *
- * The values are in 1/1000th of logical pixels, i.e. the value 100 000
- * refers to 100 pixels.
- *
  * The pointer range is constant. Where the pointer range is no longer
  * applicable, the client needs to remove the device and create and add a
  * new device with the updated pointer range.
@@ -323,7 +353,7 @@ eis_device_resume(struct eis_device *device);
  * It is a server bug to call this function on a device without the @ref
  * EIS_DEVICE_CAP_POINTER_ABSOLUTE capability.
  *
- * @return The new width in 1/1000th of logical pixels
+ * @return The new width in logical pixels
  */
 uint32_t
 eis_device_get_pointer_width(struct eis_device *device);