[PATCH 6/6] utils: Document wl_list methods

[Aaron Faanes]

---

As I understand it, a wl_list can be either content-bearing node or a list head.
I believe this is correct, but if it isn't (in other words, there is no distinction
between list heads and content-bearing elements), then this documentation is going
to be tragically incorrect.

 src/wayland-util.h | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)

diff --git a/src/wayland-util.h b/src/wayland-util.h
index 51de3f6..86d03f2 100644
--- a/src/wayland-util.h
+++ b/src/wayland-util.h
@@ -115,11 +115,75 @@ struct wl_list {
 	struct wl_list *next;
 };
 
+/** Initializes a new wl_list for use as a list.
+ *
+ * There is no need to call this method for wl_list nodes that will only be used as
+ * elements within other lists, though there is no harm in doing so.
+ *
+ * \param list The list that will be initialized.
+ *
+ * \memberof wl_list
+ */
 void wl_list_init(struct wl_list *list);
+
+/** Inserts the specified element directly after the specified list node.
+ *
+ * \param list the list that will be directly previous to \c elm
+ * \param elm The element that will be added after \c list
+ *
+ * \memberof wl_list
+ */
 void wl_list_insert(struct wl_list *list, struct wl_list *elm);
+
+/** Removes the specified wl_list node from the list that contains it.
+ *
+ * \param elm the list to remove
+ *
+ * \memberof wl_list
+ */
 void wl_list_remove(struct wl_list *elm);
+
+/** Returns the number of elements in the specified list.
+ *
+ * Prefer #wl_list_empty if you're just interested if the list is empty.
+ *
+ * \param list The list that will be queried.
+ * \return The number of elements in the specified list.
+ *
+ * \sa wl_list_empty
+ * \memberof wl_list
+ */
 int wl_list_length(const struct wl_list *list);
+
+/** Queries whether the specified list is empty.
+ *
+ * This method runs in O(1).
+ *
+ * \param list The list that will be queried.
+ * \return \c true if the list is empty, \c false otherwise
+ *
+ * \sa wl_list_length
+ * \memberof wl_list
+ */
 int wl_list_empty(const struct wl_list *list);
+
+/** Inserts all elements in the specified other list into \c list.
+ *
+ * All elements in \other will be added in order directly before \c list.
+ *
+ * \code
+ * wl_list foo; // [1, 2, 3]
+ * wl_list bar; // [4, 5, 6]
+ *
+ * wl_list_insert_list(&foo, &other);
+ * // foo now contains [4, 5, 6, 1, 2, 3]
+ * \endcode
+ *
+ * \param list The list that will be added to
+ * \param other The list that contains the elements to add.
+ *
+ * \memberof wl_list
+ */
 void wl_list_insert_list(struct wl_list *list, struct wl_list *other);
 
 /**
-- 
1.8.3.1