libei: some more API documentation

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

src/libei.h

@@ -113,7 +113,18 @@ enum ei_event_type {
 };
 
 /**
- * Create a new ei context.
+ * Create a new ei context. The context is refcounted and must be released
+ * with ei_unref().
+ *
+ * A context supports exactly one backend, set up with one of
+ * ei_setup_backend_socket() or ei_setup_backend_fd().
+ *
+ * @param user_data An opaque pointer to be returned with ei_get_user_data()
+ *
+ * @see ei_set_user_data
+ * @see ei_get_user_data
+ * @see ei_setup_backend_fd
+ * @see ei_setup_backend_socket
  */
 struct ei *
 ei_new(void *user_data);
@@ -130,26 +141,70 @@ void
 ei_configure_name(struct ei * ei, const char *name);
 
 /**
- * Set this ei context to use the socket backend.
+ * Set this ei context to use the socket backend. The ei context will
+ * connect to the socket at the given path and initiate the conversation
+ * with the EIS server listening on that socket.
+ *
+ * If the connection was successful, an event of type @ref EI_EVENT_CONNECT
+ * or @ref EI_EVENT_DISCONNECT will become available after a future call to
+ * ei_dispatch().
+ *
+ * If the connection failed, use ei_unref() to release the data allocated
+ * for this context.
+ *
+ * @return zero on success or a negative errno on failure
  */
 int
 ei_setup_backend_socket(struct ei *ei, const char *socketpath);
 
 /**
- * Initialize the ei context on the given socket
+ * Initialize the ei context on the given socket. The ei context will
+ * initiate the conversation with the EIS server listening on the other end
+ * of this socket.
+ *
+ * If the connection was successful, an event of type @ref EI_EVENT_CONNECT
+ * or @ref EI_EVENT_DISCONNECT will become available after a future call to
+ * ei_dispatch().
+ *
+ * If the connection failed, use ei_unref() to release the data allocated
+ * for this context.
+ *
+ * @return zero on success or a negative errno on failure
  */
 int
 ei_setup_backend_fd(struct ei *ei, int fd);
 
+/**
+ * Increase the refcount of this struct by one. Use ei_unref() to decrease
+ * the refcount.
+ *
+ * @return the argument passed into the function
+ */
 struct ei *
-ei_ref(struct ei *ctx);
+ei_ref(struct ei *ei);
 
+/**
+ * Decrease the refcount of this struct by one. When the refcount reaches
+ * zero, the context disconnects from the server and all allocated resources
+ * are released.
+ *
+ * @return always NULL
+ */
 struct ei *
 ei_unref(struct ei *ei);
 
+/**
+ * Set a custom data pointer for this context. libei will not look at or
+ * modify the pointer. Use ei_get_user_data() to retrieve a previously set
+ * user data.
+ */
 void
 ei_set_user_data(struct ei *ei, void *user_data);
 
+/**
+ * Return the custom data pointer for this context. libei will not look at or
+ * modify the pointer. Use ei_set_user_data() to change the user data.
+ */
 void *
 ei_get_user_data(struct ei *ei);