From e03ec948967225c8162ffecf37b59bbfc338a83a Mon Sep 17 00:00:00 2001
From: Matthias Schiffer <mschiffer@universe-factory.net>
Date: Tue, 27 May 2014 05:48:51 +0200
Subject: Lots and lots of documentation

---
 src/vector.h | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)

(limited to 'src/vector.h')

diff --git a/src/vector.h b/src/vector.h
index 0396c01..0a61341 100644
--- a/src/vector.h
+++ b/src/vector.h
@@ -23,18 +23,30 @@
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
+/**
+   \file vector.h
+
+   Typesafe dynamically sized arrays
+*/
+
 
 #pragma once
 
 #include <stdlib.h>
 
 
+/** A vector descriptor */
 typedef struct fastd_vector_desc {
 	size_t allocated;
 	size_t length;
 } fastd_vector_desc_t;
 
 
+/**
+   A type for a vector of \e type elements
+
+   \hideinitializer
+*/
 #define VECTOR(type)				\
 	struct {				\
 		fastd_vector_desc_t desc;	\
@@ -49,39 +61,91 @@ void _fastd_vector_insert(fastd_vector_desc_t *desc, void **data, void *element,
 void _fastd_vector_delete(fastd_vector_desc_t *desc, void **data, size_t pos, size_t elemsize);
 
 
+/**
+   Allocates resources for the vector \e a, starting with \e n elements
+
+   \hideinitializer
+*/
 #define VECTOR_ALLOC(v, n) ({						\
 			__typeof__(v) *_v = &(v);			\
 			_fastd_vector_alloc(&_v->desc, (void**)&_v->data, (n), sizeof(*_v->data)); \
 		})
 
+/**
+   Resizes the vector \e a to \e n elements
+
+   \hideinitializer
+*/
 #define VECTOR_RESIZE(v, n)  ({						\
 			__typeof__(v) *_v = &(v);			\
 			_fastd_vector_resize(&_v->desc, (void**)&_v->data, (n), sizeof(*_v->data)); \
 		})
 
+/**
+   Frees all resources used by the vector \e v
+
+   \hideinitializer
+*/
 #define VECTOR_FREE(v) free((v).data)
 
+/**
+   Returns the number of elements in the vector \e v
+
+   \hideinitializer
+*/
 #define VECTOR_LEN(v) ((v).desc.length)
+
+/**
+   Returns the element with index \e i in the vector \e v
+
+   \hideinitializer
+*/
 #define VECTOR_INDEX(v, i) ((v).data[i])
+
+/**
+   Returns a pointer to the vector elements of \e v
+
+   \hideinitializer
+*/
 #define VECTOR_DATA(v) ((v).data)
 
+/**
+   Inserts the element \e elem at index \e pos of vector \e v
+
+   \hideinitializer
+*/
 #define VECTOR_INSERT(v, elem, pos) ({					\
 			__typeof__(v) *_v = &(v);			\
 			__typeof__(*_v->data) _e = (elem);		\
 			_fastd_vector_insert(&_v->desc, (void**)&_v->data, &_e, (pos), sizeof(_e)); \
 		})
 
+/**
+   Adds the element \e elem at the end of vector \e v
+
+   \hideinitializer
+*/
 #define VECTOR_ADD(v, elem) ({						\
 			__typeof__(v) *_v = &(v);			\
 			__typeof__(*_v->data) _e = (elem);		\
 			_fastd_vector_insert(&_v->desc, (void**)&_v->data, &_e, _v->desc.length, sizeof(_e)); \
 		})
 
+/**
+   Deletes the element at index \e pos of vector \e v
+
+   \hideinitializer
+*/
 #define VECTOR_DELETE(v, pos) ({					\
 			__typeof__(v) *_v = &(v);			\
 			_fastd_vector_delete(&_v->desc, (void**)&_v->data, (pos), sizeof(*_v->data)); \
 		})
 
+/**
+   Performs a binary search on the vector \e v, returning a pointer to a matching vector element
+
+   \hideinitializer
+*/
 #define VECTOR_BSEARCH(key, v, cmp) ({					\
 			__typeof__(v) *_v = &(v);			\
 			const __typeof__(*_v->data) *_key = (key);	\
-- 
cgit v1.2.3