Document functions in wayland-util, wayland-hash, and connection.c

1 files changed, 44 insertions, 0 deletions

diff --git a/wayland-util.c b/wayland-util.c
index a287cce..eaec21d 100644
--- a/wayland-util.c
+++ b/wayland-util.c
@@ -25,6 +25,11 @@
 #include <string.h>
 #include "wayland-util.h"
 
+/**
+ * Initialize a wl_list object.
+ *
+ * list: Already-allocated wl_list.
+ **/
 WL_EXPORT void
 wl_list_init(struct wl_list *list)
 {
@@ -32,6 +37,13 @@ wl_list_init(struct wl_list *list)
 	list->next = list;
 }
 
+/**
+ * Add a new element to a wl_list. The new element will appear just after
+ * `list`.
+ *
+ * list: Head node of list to add to.
+ * elm: Element we are adding.
+ **/
 WL_EXPORT void
 wl_list_insert(struct wl_list *list, struct wl_list *elm)
 {
@@ -41,6 +53,12 @@ wl_list_insert(struct wl_list *list, struct wl_list *elm)
 	elm->next->prev = elm;
 }
 
+/**
+ * Remove `elm` from the list containing it. `elm` itself will still point into
+ * the list and bad things will happen if you reference it!.
+ *
+ * elm: Element to remove.
+ **/
 WL_EXPORT void
 wl_list_remove(struct wl_list *elm)
 {
@@ -48,6 +66,11 @@ wl_list_remove(struct wl_list *elm)
 	elm->next->prev = elm->prev;
 }
 
+/**
+ * Find the number of elements in `list`. The head node is not counted.
+ *
+ * list: Head element in list to count.
+ **/
 WL_EXPORT int
 wl_list_length(struct wl_list *list)
 {
@@ -64,24 +87,45 @@ wl_list_length(struct wl_list *list)
 	return count;
 }
 
+/**
+ * Determine if `list` is empty.
+ *
+ * list: Head node of list to check.
+ **/
 WL_EXPORT int
 wl_list_empty(struct wl_list *list)
 {
 	return list->next == list;
 }
 
+/**
+ * Initialize a wl_array.
+ *
+ * array: Array to initialize.
+ **/
 WL_EXPORT void
 wl_array_init(struct wl_array *array)
 {
 	memset(array, 0, sizeof *array);
 }
 
+/**
+ * Free any memory associated with a wl_array.
+ *
+ * array: Array to release.
+ **/
 WL_EXPORT void
 wl_array_release(struct wl_array *array)
 {
 	free(array->data);
 }
 
+/**
+ * Add space for one more element of size `size` to a wl_array.
+ *
+ * array: Array to add to.
+ * size: Size of each element in `array`
+ **/
 WL_EXPORT void *
 wl_array_add(struct wl_array *array, int size)
 {