From: lottaviano <lottaviano@38d2e660-2303-0410-9eaa-f027e97ec537>
Date: Mon, 3 Jan 2011 09:51:48 +0000 (+0000)
Subject: doc: Move List documentation into its own section.
X-Git-Tag: 2.7.0~305
X-Git-Url: https://codewiz.org/gitweb?a=commitdiff_plain;h=9b851504d2822d5d10b9894dd09706a39232faad;p=bertos.git

doc: Move List documentation into its own section.

git-svn-id: https://src.develer.com/svnoss/bertos/trunk@4661 38d2e660-2303-0410-9eaa-f027e97ec537
---

diff --git a/bertos/struct/list.h b/bertos/struct/list.h
index c8306354..91fe63fb 100644
--- a/bertos/struct/list.h
+++ b/bertos/struct/list.h
@@ -30,8 +30,49 @@
  * Copyright 2001, 2008 Bernie Innocenti <bernie@codewiz.org>
  * -->
  *
+ * \defgroup list General purpose lists
+ * \ingroup struct
+ * \{
+ *
  * \brief General pourpose double-linked lists
  *
+ * Lists contain nodes. You can put any custom struct into any list as long
+ * as it has a Node struct inside it. If you make the Node struct the first
+ * member of your data type, you can simply cast it to (Node *) when passing
+ * it to list functions.
+ *
+ * Lists must be initialized before use with LIST_INIT(). You can then add
+ * objects using ADDHEAD() and ADDTAIL() macros, and remove them with
+ * list_remHead() and list_remTail().
+ *
+ * You can create lists with priorities by using PriNode instead of Node as
+ * the base member struct.
+ * Use LIST_ENQUEUE() and LIST_ENQUEUE_HEAD() to insert a priority node into
+ * a list.
+ *
+ * To iterate over a list, use the macros FOREACH_NODE() and REVERSE_FOREACH_NODE()
+ * in this way:
+ * \code
+ * struct Foo
+ * {
+ *     Node n;
+ *     int a;
+ * }
+ *
+ * int main()
+ * {
+ *        List foo_list;
+ *        static Foo foo1, foo2;
+ *        Foo *fp;
+ *
+ *        LIST_INIT(&foo_list);
+ *        ADDHEAD(&foo_list, (Node *)&foo1);
+ *        INSERT_BEFORE(&foo_list, (Node *)&foo2);
+ *        FOREACH_NODE(fp, &foo_list)
+ *            fp->a = 10;
+ * }
+ * \endcode
+ *
  * \author Bernie Innocenti <bernie@codewiz.org>
  */
 
@@ -349,4 +390,6 @@ INLINE Node *list_remTail(List *l)
 	return n;
 }
 
+/** \} */ //defgroup list
+
 #endif /* STRUCT_LIST_H */