--- 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 _______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel