From 6dc85575000127630489b407c50a4b3ea87c9acb Mon Sep 17 00:00:00 2001
From: Keith Whitwell <keith@tungstengraphics.com>
Date: Thu, 17 Jul 2003 13:43:59 +0000
Subject: Merge Jose's documentation and core Mesa changes from embedded branch

---
 src/mesa/main/simple_list.h | 126 +++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 113 insertions(+), 13 deletions(-)

(limited to 'src/mesa/main/simple_list.h')

diff --git a/src/mesa/main/simple_list.h b/src/mesa/main/simple_list.h
index 2d9d4c8453..63475f6f74 100644
--- a/src/mesa/main/simple_list.h
+++ b/src/mesa/main/simple_list.h
@@ -1,3 +1,13 @@
+/**
+ * \file simple_list.h
+ * Simple macros for type-safe, intrusive lists.
+ *
+ *  Intended to work with a list sentinal which is created as an empty
+ *  list.  Insert & delete are O(1).
+ *  
+ * \author
+ *  (C) 1997, Keith Whitwell
+ */
 
 /*
  * Mesa 3-D graphics library
@@ -23,23 +33,27 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/*  Simple macros for typesafe, intrusive lists.
- *  (C) 1997, Keith Whitwell
- *
- *  Intended to work with a list sentinal which is created as an empty
- *  list.  Insert & delete are O(1).
- */
-
 
 #ifndef _SIMPLE_LIST_H
 #define _SIMPLE_LIST_H
 
+/**
+ * Remove an element from list.
+ *
+ * \param elem element to remove.
+ */
 #define remove_from_list(elem)			\
 do {						\
    (elem)->next->prev = (elem)->prev;		\
    (elem)->prev->next = (elem)->next;		\
 } while (0)
 
+/**
+ * Insert an element to the list head.
+ *
+ * \param list list.
+ * \param elem element to insert.
+ */
 #define insert_at_head(list, elem)		\
 do {						\
    (elem)->prev = list;				\
@@ -48,6 +62,12 @@ do {						\
    (list)->next = elem;				\
 } while(0)
 
+/**
+ * Insert an element to the list tail.
+ *
+ * \param list list.
+ * \param elem element to insert.
+ */
 #define insert_at_tail(list, elem)		\
 do {						\
    (elem)->next = list;				\
@@ -56,42 +76,122 @@ do {						\
    (list)->prev = elem;				\
 } while(0)
 
+/**
+ * Move an element to the list head.
+ *
+ * \param list list.
+ * \param elem element to move.
+ */
 #define move_to_head(list, elem)		\
 do {						\
    remove_from_list(elem);			\
    insert_at_head(list, elem);			\
 } while (0)
 
+/**
+ * Move an element to the list tail.
+ *
+ * \param list list.
+ * \param elem element to move.
+ */
 #define move_to_tail(list, elem)		\
 do {						\
    remove_from_list(elem);			\
    insert_at_tail(list, elem);			\
 } while (0)
 
-
+/**
+ * Make a empty list empty.
+ *
+ * \param sentinal list (sentinal element).
+ */
 #define make_empty_list(sentinal)		\
 do {						\
    (sentinal)->next = sentinal;			\
    (sentinal)->prev = sentinal;			\
 } while (0)
 
-
+/**
+ * Get list first element.
+ *
+ * \param list list.
+ *
+ * \return pointer to first element.
+ */
 #define first_elem(list)       ((list)->next)
+
+/**
+ * Get list last element.
+ *
+ * \param list list.
+ *
+ * \return pointer to last element.
+ */
 #define last_elem(list)        ((list)->prev)
+
+/**
+ * Get next element.
+ *
+ * \param elem element.
+ *
+ * \return pointer to next element.
+ */
 #define next_elem(elem)        ((elem)->next)
+
+/**
+ * Get previous element.
+ *
+ * \param elem element.
+ *
+ * \return pointer to previous element.
+ */
 #define prev_elem(elem)        ((elem)->prev)
+
+/**
+ * Test whether element is at end of the list.
+ * 
+ * \param list list.
+ * \param elem element.
+ * 
+ * \return non-zero if element is at end of list, or zero otherwise.
+ */
 #define at_end(list, elem)     ((elem) == (list))
+
+/**
+ * Test if a list is empty.
+ * 
+ * \param list list.
+ * 
+ * \return non-zero if list empty, or zero otherwise.
+ */
 #define is_empty_list(list)    ((list)->next == (list))
 
+/**
+ * Walk through the elements of a list.
+ *
+ * \param ptr pointer to the current element.
+ * \param list list.
+ *
+ * \note It should be followed by a { } block or a single statement, as in a \c
+ * for loop.
+ */
 #define foreach(ptr, list)     \
         for( ptr=(list)->next ;  ptr!=list ;  ptr=(ptr)->next )
 
-/* Kludgey - Lets you unlink the current value during a list
- *           traversal.  Useful for free()-ing a list, element
- *           by element.
+/**
+ * Walk through the elements of a list.
+ *
+ * Same as #foreach but lets you unlink the current value during a list
+ * traversal.  Useful for freeing a list, element by element.
+ * 
+ * \param ptr pointer to the current element.
+ * \param t temporary pointer.
+ * \param list list.
+ *
+ * \note It should be followed by a { } block or a single statement, as in a \c
+ * for loop.
  */
 #define foreach_s(ptr, t, list)   \
         for(ptr=(list)->next,t=(ptr)->next; list != ptr; ptr=t, t=(t)->next)
 
-
 #endif
-- 
cgit v1.2.3