X-Git-Url: http://mj.ucw.cz/gitweb/?a=blobdiff_plain;f=lib%2Flists.h;h=39036913f8d99a3d8eac7bdb0c1c1cce1ace083a;hb=348ef39c1cf89a38a24ebbd221a9b0a3078cfc1c;hp=0c0ab0f6069b6c57c01832626ae4559c93c07579;hpb=1571781022499a9d0c32d249f89945d034d1cbff;p=libucw.git

diff --git a/lib/lists.h b/lib/lists.h
index 0c0ab0f6..39036913 100644
--- a/lib/lists.h
+++ b/lib/lists.h
@@ -1,11 +1,27 @@
 /*
- *	Sherlock Library -- Linked Lists
+ *	UCW Library -- Linked Lists
  *
  *	(c) 1997--1999 Martin Mares <mj@ucw.cz>
+ *
+ *	This software may be freely distributed and used according to the terms
+ *	of the GNU Lesser General Public License.
  */
 
-#ifndef _SHERLOCK_LISTS_H
-#define _SHERLOCK_LISTS_H
+#ifndef _UCW_LISTS_H
+#define _UCW_LISTS_H
+
+/*
+ * I admit the list structure is very tricky and also somewhat awkward,
+ * but it's both efficient and easy to manipulate once one understands the
+ * basic trick: The list head always contains two synthetic nodes which are
+ * always present in the list: the head and the tail. But as the `next'
+ * entry of the tail and the `prev' entry of the head are both NULL, the
+ * nodes can overlap each other:
+ *
+ *     head    head_node.next
+ *     null    head_node.prev  tail_node.next
+ *     tail                    tail_node.prev
+ */
 
 typedef struct node {
   struct node *next, *prev;
@@ -37,7 +53,7 @@ void add_tail_list(list *, list *);
 void init_list(list *);
 void insert_node(node *, node *);
 
-#if !defined(_SHERLOCK_LISTS_C) && defined(__GNUC__)
+#if !defined(_UCW_LISTS_C) && defined(__GNUC__)
 #define LIST_INLINE extern inline
 #include "lib/lists.c"
 #undef LIST_INLINE