1 files changed, 61 insertions, 0 deletions

diff --git a/lib/lists.c b/lib/lists.c
index c14eb4c7..6d97ff50 100644
--- a/lib/lists.c
+++ b/lib/lists.c
@@ -6,11 +6,36 @@
  *	Can be freely distributed and used under the terms of the GNU GPL.
  */
 
+/**
+ * DOC: Linked lists
+ *
+ * The BIRD library provides a set of functions for operating on linked
+ * lists. The lists are internally represented as standard doubly linked
+ * lists with synthetic head and tail which makes all the basic operations
+ * run in constant time and contain no extra end-of-list checks. Each list
+ * is described by a &list structure, nodes can have any format as long
+ * as they start with a &node structure. If you want your nodes to belong
+ * to multiple lists at once, you can embed multiple &node structures in them
+ * and use the SKIP_BACK() macro to calculate a pointer to the start of the
+ * structure from a &node pointer, but beware of obscurity.
+ *
+ * There also exist safe linked lists (&slist, &snode and all functions
+ * being prefixed with |s_|) which support asynchronous walking very
+ * similar to that used in the &fib structure.
+ */
+
 #define _BIRD_LISTS_C_
 
 #include "nest/bird.h"
 #include "lib/lists.h"
 
+/**
+ * add_tail - append a node to a list
+ * @l: linked list
+ * @n: list node
+ *
+ * add_tail() takes a node @n and appends it at the end of the list @l.
+ */
 LIST_INLINE void
 add_tail(list *l, node *n)
 {
@@ -22,6 +47,13 @@ add_tail(list *l, node *n)
   l->tail = n;
 }
 
+/**
+ * add_head - prepend a node to a list
+ * @l: linked list
+ * @n: list node
+ *
+ * add_head() takes a node @n and prepends it at the start of the list @l.
+ */
 LIST_INLINE void
 add_head(list *l, node *n)
 {
@@ -33,6 +65,14 @@ add_head(list *l, node *n)
   l->head = n;
 }
 
+/**
+ * insert_node - insert a node to a list
+ * @n: a new list node
+ * @after: a node of a list
+ *
+ * Inserts a node @n to a linked list after an already inserted
+ * node @after.
+ */
 LIST_INLINE void
 insert_node(node *n, node *after)
 {
@@ -44,6 +84,12 @@ insert_node(node *n, node *after)
   z->prev = n;
 }
 
+/**
+ * rem_node - remove a node from a list
+ * @n: node to be removed
+ *
+ * Removes a node @n from the list it's linked in.
+ */
 LIST_INLINE void
 rem_node(node *n)
 {
@@ -54,6 +100,13 @@ rem_node(node *n)
   x->prev = z;
 }
 
+/**
+ * init_list - create an empty list
+ * @l: list
+ *
+ * init_list() takes a &list structure and initializes its
+ * fields, so that it represents an empty list.
+ */
 LIST_INLINE void
 init_list(list *l)
 {
@@ -62,6 +115,14 @@ init_list(list *l)
   l->tail = (node *) &l->head;
 }
 
+/**
+ * add_tail_list - concatenate two lists
+ * @to: destination list
+ * @l: source list
+ *
+ * This function appends all elements of the list @l to
+ * the list @to in constant time.
+ */
 LIST_INLINE void
 add_tail_list(list *to, list *l)
 {