Document the linked list support code.

diff --git a/include/wine/list.h b/include/wine/list.h
index 1e311795b15cd071eb6c6ee206d05f1649b21951..6d27fad62300d248ff37a308a41e7d1a75cb03d9 100644 (file)
--- 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 )
 {