--- a/LinkedList.st	Sat Jan 11 13:14:19 1997 +0100
+++ b/LinkedList.st	Sat Jan 11 13:16:28 1997 +0100
@@ -43,7 +43,21 @@
     LinkedList does not care for storage; all it does is handling
     chained link elements, which must respond to #nextLink/#nextLink:.
     (i.e. any object which can do this, can be used as elements of a linked
-    list).
+     list). 
+    An abstract superclass for linkElements is Link; a concrete class is
+    ValueLink, which holds a reference to some object.
+
+    [warning:]
+        Be careful when subclassing Link, since there is a big drawback,
+        which may be overlooked by beginners: 
+            a Link element can only be in one LinkedList 
+            - adding the same element to another LinkedList
+            will remove it from the first as a side effect.
+        Therefore, NEVER simply add something to a linkedList (except for
+        valueLinks) unless you know what you do.
+        The ST-80 implementors probably wanted this behavior, to move
+        processes from the waitingList to runLists and vice versa;
+        however, literature seems to not point this out enough.
 
     Although LinkedList is a subclass of SequenceableCollection (and therefore
     supports indexed access via at:), you should be careful in using it or
@@ -62,6 +76,9 @@
 
     [author:]
         Claus Gittinger
+
+    [see also:]
+        Link ValueLink Process
 "
 !
 
@@ -387,5 +404,5 @@
 !LinkedList class methodsFor:'documentation'!
 
 version
-    ^ '$Header: /cvs/stx/stx/libbasic/LinkedList.st,v 1.26 1996-05-09 14:26:36 cg Exp $'
+    ^ '$Header: /cvs/stx/stx/libbasic/LinkedList.st,v 1.27 1997-01-11 12:16:08 cg Exp $'
 ! !