From b4552374cacdc79fb697b121bd3222496d60f772 Mon Sep 17 00:00:00 2001
From: Peter Hutterer <peter.hutterer@who-t.net>
Date: Tue, 4 Aug 2020 11:09:19 +1000
Subject: [PATCH] libei: documentation updates

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
---
 src/libei.h | 46 ++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 38 insertions(+), 8 deletions(-)

diff --git a/src/libei.h b/src/libei.h
index b389c67..58b490a 100644
--- a/src/libei.h
+++ b/src/libei.h
@@ -142,18 +142,48 @@ ei_portal_connect(struct ei *ei);
 int
 ei_dbus_connect(struct ei *ei);
 
+/**
+ * libei keeps a single file descriptor for all events. Cal
+ * libei_dispatch() if any events become available on this fd.
+ */
 int
 ei_get_fd(struct ei *ei);
 
+/**
+ * Main event dispatchment function. Reads events of the file descriptors
+ * and processes them internally. Use libei_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 libei_get_fd().
+ */
 void
 ei_dispatch(struct ei *ei);
 
+/**
+ * Return the next event from the event queue, removing it from the queue.
+ *
+ * The returned object must be released by the caller with ei_event_unref()
+ */
 struct ei_event *
 ei_get_event(struct ei *ei);
 
+/**
+ * Return the type of the next event in the event queue or @ref
+ * EI_EVENT_NONE if none are available. This function does not remove the
+ * event from the queue.
+ */
 enum ei_event_type
 ei_next_event_type(struct ei *ei);
 
+/**
+ * Release resources associated with this event. This function always
+ * returns NULL.
+ *
+ * Events can only be unref'd by the caller. They should be considered
+ * transient data and not be held longer than required.
+ */
 struct ei_event *
 ei_event_unref(struct ei_event *event);
 
@@ -164,19 +194,16 @@ struct ei_device *
 ei_device_unref(struct ei_device *device);
 
 /**
- * Create a new device. This device is local to the client and should
- * only used for initial device configuration. It does not represent the
- * server-created device until the @ref EI_EVENT_DEVICE_ADDED for this
- * device has been received.
+ * Create a new device. This device is a proxy representing the server's
+ * device and should be used for initial device configuration. It does not
+ * represent the server-created device until the @ref EI_EVENT_DEVICE_ADDED
+ * for this device has been received.
  *
  * Use the configure API (e.g. ei_device_configure_capability()) to set up
  * the device, then call ei_device_add() to request creation of the device
  * by the server.
  *
- * The refcount of the returned device is 1, use ei_device_unref() to
- * release resources associated with this device..
- *
- * @param ei The context
+ * The returned object must be released by the caller with ei_event_unref()
  */
 struct ei_device *
 ei_device_new(struct ei *ei);
@@ -189,6 +216,9 @@ ei_device_new(struct ei *ei);
  *
  * This function has no effect if called after ei_device_add()
  *
+ * libei may quietly ignore names of unreasonable length. This is not
+ * something a normal caller ever needs to worry about.
+ *
  * @param name A name suggestion for the device
  */
 void