[PATCH] wayland-util: document wl_map usage

[Tiago Vignatti]

Signed-off-by: Tiago Vignatti <tiago.vignatti at intel.com>
---
 src/wayland-util.h |   14 ++++++++++++++
 1 files changed, 14 insertions(+), 0 deletions(-)

diff --git a/src/wayland-util.h b/src/wayland-util.h
index 76e0f1d..b0dd178 100644
--- a/src/wayland-util.h
+++ b/src/wayland-util.h
@@ -149,6 +149,20 @@ void wl_array_release(struct wl_array *array);
 void *wl_array_add(struct wl_array *array, int size);
 void wl_array_copy(struct wl_array *array, struct wl_array *source);
 
+/**
+ * wl_map - array with a free-list
+ *
+ * The map data structure can be used in one of two modes: either you use it
+ * to allocate IDs in constant time by using wl_map_insert_new() and
+ * wl_map_remove(). In this way, wl_map_insert_new() will allocate and return a
+ * new ID, wl_map_remove() will put the removed entry on a free list so insert
+ * can find it in constant time.  This is how the clients allocate IDs and how
+ * the server allocates global object names.
+ *
+ * The other way is just wl_map_insert_at(), which will insert the given
+ * pointer and the specified index.  This is how you use it when somebody
+ * else allocates the IDs and you're just keeping track of the mapping.
+ */
 struct wl_map {
 	struct wl_array entries;
 	uint32_t free_list;
-- 
1.7.2.2