--- a/SharedCollection.st	Fri Aug 23 11:34:47 2019 +0200
+++ b/SharedCollection.st	Fri Aug 23 11:37:30 2019 +0200
@@ -40,23 +40,22 @@
 
 documentation
 "
-    Instances of this class provide synchronized access (of multiple processes) 
-    to a collection.
+    Instances of this class provide synchronized access (of multiple processes) to a collection.
+    Any message sent to instances are protected by an internal access lock, 
+    to prevent simultaneous access from different threads. 
 
     Notice: 
         the message-forwarding is done by catching subclassResponsibility and
         doesNotUnderstand errors.
-
-    For performance, and for more complex operation-atomicy, more messages might need
-    an explicit handling. 
-    See the implementation of #at: / #at:put: and #size for examples.
+        For performance, and for more complex operation-atomicy, 
+        more messages might need an explicit handling. 
+        See the implementation of #at: / #at:put: and #size for examples.
 
     [auhor:]
         Claus Gittinger
 
     [see also:]
-        Semaphore RecursionLock
-        SharedQueue
+        Semaphore RecursionLock SharedQueue
         #synchronized: method in Object.
 "
 !
@@ -102,7 +101,8 @@
 !SharedCollection methodsFor:'accessing'!
 
 accessLock
-    "for protocol compatibility with SharedQueue"
+    "returns the internal lock (an instance of RecursionLock).
+     For protocol compatibility with SharedQueue"
     
     ^ accessLock
 
@@ -110,12 +110,17 @@
 !
 
 synchronizationSemaphore
+    "returns the internal lock (an instance of RecursionLock)"
+
     ^ accessLock
 ! !
 
 !SharedCollection methodsFor:'converting'!
 
 asSharedCollection
+    "return a shared collection on the receiver.
+     because the receiver is already synchronized, itself is returned."
+
     ^ self.
 ! !
 
@@ -135,6 +140,8 @@
 !SharedCollection methodsFor:'initialization'!
 
 initializeFor:aCollection
+    "private; initializes the private access lock"
+
     accessLock := RecursionLock name:'SharedCollection'.
     realCollection := aCollection.
 
@@ -156,6 +163,8 @@
 !
 
 at:index
+    "retrieve the element at index while locked"
+
     ^ accessLock critical:[
         realCollection at:index
     ].
@@ -164,6 +173,8 @@
 !
 
 at:index put:value
+    "update the element at index while locked"
+
     ^ accessLock critical:[
         realCollection at:index put:value
     ].
@@ -172,6 +183,8 @@
 !
 
 do:aBlock
+    "enumerate the elements while locked"
+
     ^ accessLock critical:[
         realCollection do:aBlock
     ].
@@ -181,7 +194,8 @@
 !
 
 doesNotUnderstand:aMessage
-    "catches everything not understood by the collection protocol"
+    "catches everything not understood by the collection protocol,
+     and forwards the message to the underlying collection while locked"
 
     ^ accessLock critical:[
         aMessage sendTo:realCollection