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

5 files changed, 203 insertions, 5 deletions

diff --git a/connection.c b/connection.c
index 5de4380..d969531 100644
--- a/connection.c
+++ b/connection.c
@@ -32,6 +32,13 @@
 #include "wayland-util.h"
 #include "connection.h"
 
+/**
+ * A 4KiB ring buffer of bytes.
+ *
+ * data: The contents of the buffer.
+ * head: Position of the buffer head.
+ * tail: Position of the buffer tail.
+ **/
 struct wl_buffer {
 	char data[4096];
 	int head, tail;
diff --git a/wayland-glib.c b/wayland-glib.c
index fa7a9f5..71d7651 100644
--- a/wayland-glib.c
+++ b/wayland-glib.c
@@ -25,6 +25,15 @@
 #include "wayland-client.h"
 #include "wayland-glib.h"
 
+/**
+ * A GLib source for events generated by a Wayland display.
+ *
+ * source: The base GLib source.
+ * pfd: The display file descriptor.
+ * mask: Mask indicating what operations are permitted for this display through
+ *       this source.
+ * display: The display this source watches.
+ **/
 typedef struct _WlSource {
 	GSource source;
 	GPollFD pfd;
@@ -32,6 +41,13 @@ typedef struct _WlSource {
 	struct wl_display *display;
 } WlSource;
 
+/**
+ * Prepare a WlSource for polling on its descriptor.
+ *
+ * base: GSource from a WLSource to prepare.
+ * timeout: Where GLib expects to receive the maximum timeout for this
+ *          descriptor. For WlSource it will always be set to -1.
+ **/
 static gboolean
 wl_glib_source_prepare(GSource *base, gint *timeout)
 {
@@ -50,6 +66,12 @@ wl_glib_source_prepare(GSource *base, gint *timeout)
 	return FALSE;
 }
 
+/**
+ * Check a WlSource to see if anything was left pending last time it was
+ * polled.
+ *
+ * base: GSource base for a WlSource.
+ **/
 static gboolean
 wl_glib_source_check(GSource *base)
 {
@@ -58,6 +80,13 @@ wl_glib_source_check(GSource *base)
 	return source->pfd.revents;
 }
 
+/**
+ * Dispatch events from a WlSource.
+ *
+ * base: GSource base for a WlSource.
+ * callback: Callback glib has assigned for events on this source.
+ * data: Data glib has associated with `callback`.
+ **/
 static gboolean
 wl_glib_source_dispatch(GSource *base,
 			GSourceFunc callback,
@@ -71,6 +100,7 @@ wl_glib_source_dispatch(GSource *base,
 	return TRUE;
 }
 
+/* GLib handlers for a WlSource */
 static GSourceFuncs wl_glib_source_funcs = {
 	wl_glib_source_prepare,
 	wl_glib_source_check,
@@ -78,6 +108,7 @@ static GSourceFuncs wl_glib_source_funcs = {
 	NULL
 };
 
+/* FIXME: Comment needed */
 static int
 wl_glib_source_update(uint32_t mask, void *data)
 {
@@ -88,6 +119,11 @@ wl_glib_source_update(uint32_t mask, void *data)
 	return 0;
 }
 
+/**
+ * Create a new WlSource.
+ *
+ * display: Display the new WlSource should watch.
+ **/
 GSource *
 wl_glib_source_new(struct wl_display *display)
 {
diff --git a/wayland-hash.c b/wayland-hash.c
index 2d36f5c..360ad67 100644
--- a/wayland-hash.c
+++ b/wayland-hash.c
@@ -36,11 +36,30 @@
 
 #include "wayland-util.h"
 
+/**
+ * An entry in a wl_hash_table.
+ *
+ * hash: The hash value for the entry.
+ * data: The data stored at this entry.
+ **/
 struct hash_entry {
 	uint32_t hash;
 	void *data;
 };
 
+/**
+ * A hash table for arbitrary data, with open addressing collision resolution.
+ *
+ * table: The array of entries in the table.
+ * size: Size of `table`.
+ * rehash: Used to calculate the interval for reprobing.
+ * max_entries: Maximum number of entries that should be put in this table
+ * 	before we rehash it.
+ * size_index: What category of size this hash table is in. Typically log[2]
+ * 	max_entries.
+ * entries: Number of entries that have been filled in in `table`.
+ * deleted_entries: Number of entries in `table` that have been marked deleted.
+ **/
 struct wl_hash_table {
 	struct hash_entry *table;
 	uint32_t size;
@@ -51,14 +70,17 @@ struct wl_hash_table {
 	uint32_t deleted_entries;
 };
 
-/*
+/* Dummy object to point deleted entries to */
+static const uint32_t deleted_data;
+
+/**
+ * Table to determine the maximum entries, size, and rehash value for a hash
+ * table.
+ *
  * From Knuth -- a good choice for hash/rehash values is p, p-2 where
  * p and p-2 are both prime.  These tables are sized to have an extra 10%
  * free to avoid exponential performance degradation as the hash table fills
- */
-
-static const uint32_t deleted_data;
-
+ **/
 static const struct {
    uint32_t max_entries, size, rehash;
 } hash_sizes[] = {
@@ -95,24 +117,42 @@ static const struct {
     { 2147483648ul,	2362232233ul,	2362232231ul}
 };
 
+/**
+ * Determine if the given entry does not have a value associated with it.
+ *
+ * entry: Entry to test.
+ **/
 static int
 entry_is_free(struct hash_entry *entry)
 {
 	return entry->data == NULL;
 }
 
+/**
+ * Determine if the given entry has been deleted.
+ *
+ * entry: Entry to test.
+ **/
 static int
 entry_is_deleted(struct hash_entry *entry)
 {
 	return entry->data == &deleted_data;
 }
 
+/**
+ * Determine if the given entry has a valid value associated with it.
+ *
+ * entry: Entry to test.
+ **/
 static int
 entry_is_present(struct hash_entry *entry)
 {
 	return entry->data != NULL && entry->data != &deleted_data;
 }
 
+/**
+ * Create and return a new wl_hash_table object, ready to be operated on.
+ **/
 WL_EXPORT struct wl_hash_table *
 wl_hash_table_create(void)
 {
@@ -184,6 +224,12 @@ hash_table_search(struct wl_hash_table *ht, uint32_t hash)
 	return NULL;
 }
 
+/**
+ * Lookup the entry in `ht` for hash `hash` and return the value associated.
+ *
+ * ht: Hash table to search.
+ * hash: Hash value to find.
+ **/
 WL_EXPORT void *
 wl_hash_table_lookup(struct wl_hash_table *ht, uint32_t hash)
 {
@@ -196,6 +242,13 @@ wl_hash_table_lookup(struct wl_hash_table *ht, uint32_t hash)
 	return NULL;
 }
 
+/**
+ * Rebuild `ht` to accomodate a different number of values.
+ *
+ * ht: Hash table to rebuild.
+ * new_size_index: Index into `hash_sizes` global array containing new hash
+ * 	table dimensions.
+ **/
 static void
 hash_table_rehash(struct wl_hash_table *ht, int new_size_index)
 {
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)
 {
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;