[xiph-commits] r3716 - liboggz/trunk/src/liboggz

[giles at svn.annodex.net]

Author: giles
Date: 2008-09-11 10:23:52 -0700 (Thu, 11 Sep 2008)
New Revision: 3716

Modified:
   liboggz/trunk/src/liboggz/oggz_vector.h
Log:
Add doxygen headers to the internal vector module.


Modified: liboggz/trunk/src/liboggz/oggz_vector.h
===================================================================
--- liboggz/trunk/src/liboggz/oggz_vector.h	2008-08-20 02:19:53 UTC (rev 3715)
+++ liboggz/trunk/src/liboggz/oggz_vector.h	2008-09-11 17:23:52 UTC (rev 3716)
@@ -40,9 +40,17 @@
 typedef int (*OggzFindFunc) (void * data, long serialno);
 typedef int (*OggzCmpFunc) (const void * a, const void * b, void * user_data);
 
+/**
+ * Create a new vector object.
+ * \retval a pointer to the new vector.
+ * \retval NULL on failure.
+ */
 OggzVector *
 oggz_vector_new (void);
 
+/**
+ * Destroy a vector object.
+ */
 void
 oggz_vector_delete (OggzVector * vector);
 
@@ -61,19 +69,41 @@
 long
 oggz_vector_nth_l (OggzVector * vector, int n);
 
+/**
+ * Call a function on each element of a vector, in order.
+ * \param vector The OggzVector to iterate over
+ * \param func The OggzFunc to be called on each element
+ * \retval 0 on success
+ */
 int
 oggz_vector_foreach (OggzVector * vector, OggzFunc func);
 
+/**
+ * Call a function with a userdata pointer on each element
+ * of a vector, in order. This allows the function to access
+ * shared data when operating on the element sequence.
+ * \param vector The OggzVector to iterate over
+ * \param func The OggzFunc1 to be called on each element
+ * \param arg The userdata pointer to be passed to the function
+ * along with the vector member
+ * \retval 0 on success
+ */
 int
 oggz_vector_foreach1 (OggzVector * vector, OggzFunc1 func, void *arg);
 
+/**
+ * Return the number of elements in a vector.
+ * \param vector The vector to query
+ * \retval The number of elements
+ */
 int
 oggz_vector_size (OggzVector * vector);
 
 /**
  * Add an element to a vector. If the vector has a comparison function,
  * the new element is inserted in sorted order, otherwise it is appended
- * to the tail.
+ * to the tail. Use this function to add pointer elements to the vector.
+ * Use ogg_vector_insert_l for long values.
  * \param vector An OggzVector
  * \param data The new element to add
  * \retval data If the element was successfully added
@@ -82,6 +112,16 @@
 void *
 oggz_vector_insert_p (OggzVector * vector, void * data);
 
+/**
+ * Add an element to a vector. If the vector has a comparison function,
+ * the new element is inserted in sorted order, otherwise it is appended
+ * to the tail. Use this function to add long value elements to the
+ * vector. Use ogg_vector_insert_p for pointer values.
+ * \param vector An OggzVector
+ * \param ldata The new element to add
+ * \retval ldata If the element was successfully added
+ * \retval -1L If adding the element failed
+ */
 long
 oggz_vector_insert_l (OggzVector * vector, long ldata);
 
@@ -101,10 +141,29 @@
 OggzVector *
 oggz_vector_remove_l (OggzVector * vector, long ldata);
 
+/**
+ * Set a comparison function for a vector.
+ * Vectors can be sorted, or stored in append order, depending on
+ * whether they have a comparison function defined. When a comparison
+ * function is first set, it will be used to sort the entire vector,
+ * and subsequence insertions will maintain the sort. If no comparison
+ * function is set, new elements are appended at the end of the vector.
+ * Call oggz_vector_set_cmp(vector, NULL, NULL) to remove the current
+ * comparison function. This does not affect the member order.
+ * \param vector the vector to associate the comparison function with
+ * \param compare the OggzCmpFunc to use for comparisons
+ * \param user_data private data pointer for the compare function
+ * \retval 0 on success
+ */
 int
 oggz_vector_set_cmp (OggzVector * vector, OggzCmpFunc compare,
 		     void * user_data);
 
+/**
+ * Pop a member off a vector.
+ * \retval pointer to the popped member
+ * \retval NULL if the vector is empty
+ */
 void *
 oggz_vector_pop (OggzVector * vector);