--- a/MappedCollection.st	Mon Aug 12 00:12:49 2019 +0200
+++ b/MappedCollection.st	Mon Aug 12 10:48:19 2019 +0200
@@ -1,3 +1,5 @@
+"{ Encoding: utf8 }"
+
 "
  COPYRIGHT (c) 1993 by Claus Gittinger
 	      All Rights Reserved
@@ -39,10 +41,14 @@
 documentation
 "
     MappedCollections represent collections of objects that are indirectly indexed by names.
-    There are really two collections involved: domain and a map.  The map maps
-    between external names and indices into domain, which contains the
-    real association.  In order to work properly, the domain and map objects must
-    be instances of a subclass of SequenceableCollection or Dictionary. 
+    There are really two collections involved: domain and a map.  
+    The map maps between external names and indices into domain, 
+    which contains the real association.  
+    In order to work properly, the domain and map objects must
+    be instances of a subclass of SequenceableCollection or Dictionary.
+    The valueDomain of the map must be the keyDomain of the domain collection.
+    i.e. 
+        mappedCollection at:k   ==>  domain at:(map at:k)
 
     [author:]
         Claus Gittinger
@@ -52,9 +58,9 @@
 examples
 "
                                             [exBegin]
-    |mapped dict|
+    |mapped keyMapping|
 
-    dict := Dictionary new
+    keyMapping := Dictionary new
                 at:'uno' put:1;
                 at:'due' put:2;
                 at:'tre' put:3;
@@ -63,7 +69,7 @@
 
     mapped := MappedCollection
                     collection:#(one two three four)
-                    map:dict.
+                    map:keyMapping.
 
     mapped at:'tre'.
     mapped select:[:each| each ~= 'two']