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

1 files changed, 58 insertions, 0 deletions

diff --git a/wayland-util.h b/wayland-util.h
index ed4acbc..dfd0efd 100644
--- a/wayland-util.h
+++ b/wayland-util.h
@@ -32,10 +32,38 @@
 #define WL_EXPORT
 #endif
 
+/**
+ * Number of elements in a static array.
+ *
+ * a: Array to find length of.
+ **/
 #define ARRAY_LENGTH(a) (sizeof (a) / sizeof (a)[0])
+
+/**
+ * Round `n` to the next `a`.
+ *
+ * n: Value to round.
+ * a: Degree to round to. Must be a power of 2.
+ **/
 #define ALIGN(n, a) ( ((n) + ((a) - 1)) & ~((a) - 1) )
+
+/**
+ * Divide `n` by `a`, rounding up, rather than truncating as in integer
+ * division.
+ *
+ * n: Dividend.
+ * a: Divisor.
+ **/
 #define DIV_ROUNDUP(n, a) ( ((n) + ((a) - 1)) / (a) )
 
+/**
+ * Get a pointer to a struct of type `type` which has a member `member`
+ * pointed to by `ptr`.
+ *
+ * type: Type of struct to return.
+ * member: Member within the struct we have the address of.
+ * ptr: Pointer to `member` within the struct we want to return.
+ **/
 #define container_of(ptr, type, member) ({			\
 	const typeof( ((type *)0)->member ) *__mptr = (ptr);	\
 	(type *)( (char *)__mptr - offsetof(type,member) );})
@@ -74,6 +102,12 @@ 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);
 
 
+/**
+ * Standard doubly-linked list node.
+ *
+ * prev: Previous entry.
+ * next: Next entry.
+ **/
 struct wl_list {
 	struct wl_list *prev;
 	struct wl_list *next;
@@ -85,15 +119,39 @@ void wl_list_remove(struct wl_list *elm);
 int wl_list_length(struct wl_list *list);
 int wl_list_empty(struct wl_list *list);
 
+/**
+ * Get a void* pointer which precedes `ptr` in address space by the offset of
+ * `member` within `type`.
+ *
+ * ptr: Base pointer.
+ * sample: Struct to calculate offset relative to.
+ * member: Member within struct to find offset of.
+ **/
 #define __container_of(ptr, sample, member)				\
 	(void *)((char *)(ptr)	-					\
 		 ((char *)&(sample)->member - (char *)(sample)))
 
+/**
+ * Iterate through a series of structures linked by a wl_list, starting at (but
+ * not including) `head`, where `member` is a wl_list member of `pos`. At each
+ * iteration of the loop, `pos` will point to the current entry.
+ *
+ * pos: Variable to store current entry in for each iteration.
+ * head: Head of list.
+ * member: Member of `pos` linking it to the list.
+ **/
 #define wl_list_for_each(pos, head, member)				\
 	for (pos = __container_of((head)->next, pos, member);		\
 	     &pos->member != (head);					\
 	     pos = __container_of(pos->member.next, pos, member))
 
+/**
+ * A dynamically allocated array.
+ *
+ * size: Number of elements in the array.
+ * alloc: Amount of space allocated for the array.
+ * data: Contents of the array.
+ **/
 struct wl_array {
 	uint32_t size;
 	uint32_t alloc;