From ac93a3d3d74f683345bdce8cb8388532540f3f49 Mon Sep 17 00:00:00 2001 From: Yuval Fledel Date: Mon, 29 Nov 2010 21:29:10 +0200 Subject: [PATCH] Document wl_list Comments only. --- wayland/wayland-util.h | 30 +++++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/wayland/wayland-util.h b/wayland/wayland-util.h index ebac305..76d703a 100644 --- a/wayland/wayland-util.h +++ b/wayland/wayland-util.h @@ -77,7 +77,35 @@ void *wl_hash_table_lookup(struct wl_hash_table *ht, uint32_t hash); int wl_hash_table_insert(struct wl_hash_table *ht, uint32_t hash, void *data); void wl_hash_table_remove(struct wl_hash_table *ht, uint32_t hash); - +/** + * wl_list - linked list + * + * The list head is of "struct wl_list" type, and must be initialized + * using wl_list_init(). All entries in the list must be of the same + * type. The item type must have a "struct wl_list" member. This + * member will be initialized by wl_list_insert(). There is no need to + * call wl_list_init() on the individual item. To query if the list is + * empty in O(1), use wl_list_empty(). + * + * Let's call the list reference "struct wl_list foo_list", the item type as + * "item_t", and the item member as "struct wl_list link". The following code + * + * The following code will initialize a list: + * + * wl_list_init(foo_list); + * wl_list_insert(foo_list, item1); Pushes item1 at the head + * wl_list_insert(foo_list, item2); Pushes item2 at the head + * wl_list_insert(item2, item3); Pushes item3 after item2 + * + * The list now looks like [item2, item3, item1] + * + * Will iterate the list in ascending order: + * + * item_t *item; + * wl_list_for_each(item, foo_list, link) { + * Do_something_with_item(item); + * } + */ struct wl_list { struct wl_list *prev; struct wl_list *next; -- 2.7.4