From 4328ec4180930e6369293f04d8cceaac900a4860 Mon Sep 17 00:00:00 2001
From: Mike Hearn <mike@navi.cx>
Date: Sat, 6 Nov 2004 03:45:49 +0000
Subject: [PATCH] Document the linked list support code.

---
 include/wine/list.h | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/include/wine/list.h b/include/wine/list.h
index 1e311795b15..6d27fad6230 100644
--- a/include/wine/list.h
+++ b/include/wine/list.h
@@ -27,6 +27,41 @@ struct list
     struct list *prev;
 };
 
+/* Define a list like so:
+ *
+ *   struct gadget
+ *   {
+ *       struct list  entry;   <-- doesn't have to be the first item in the struct
+ *       int          a, b;
+ *   };
+ *
+ *   static struct list global_gadgets = LIST_INIT( global_gadgets );
+ *
+ * or
+ *
+ *   struct some_global_thing
+ *   {
+ *       struct list gadgets;
+ *   };
+ *
+ *   list_init( &some_global_thing->gadgets );
+ *
+ * Manipulate it like this:
+ *
+ *   list_add_head( &global_gadgets, &new_gadget->entry );
+ *   list_remove( &new_gadget->entry );
+ *   list_add_after( &some_random_gadget->entry, &new_gadget->entry );
+ *
+ * And to iterate over it:
+ *
+ *   struct list *cursor;
+ *   LIST_FOR_EACH( cursor, &global_gadgets )
+ *   {
+ *       struct gadget *gadget = LIST_ENTRY( cursor, struct gadget, entry );
+ *   }
+ *
+ */
+
 /* add an element after the specified one */
 inline static void list_add_after( struct list *elem, struct list *to_add )
 {