--- a/Array.st	Fri Apr 25 15:39:09 2014 +0200
+++ b/Array.st	Mon Apr 28 15:08:21 2014 +0200
@@ -36,10 +36,10 @@
 
 documentation
 "
-    Instances of Array store general objects; the arrays size is fixed,
-    therefore add:/remove: are not allowed.
+    Instances of Array store general objects; 
+    an array's size is fixed, therefore add:/remove: are not allowed.
     (actually, #add: is implemented for compatibility with smalltalks which
-     provide it, but it is very slow and outputs an annoying warning message ...)
+     provide it, but it is very slow and outputs an annoying warning message...)
 
     Access to the individual elements is via an integer index,
     using the well-known access messages #at: and #at:put:.
@@ -51,14 +51,13 @@
 
     Notice that Array is a built-in class
     (i.e. the VM knows about its representation).
-    Therefore it is NOT possible to add named instance variables or change
-    Arrays inheritance.
+    Therefore it is NOT possible to add named instance variables or change Arrays inheritance.
     However, subclassing is allowed of course
     - even with added named instance variables.
 
     Literal arrays (i.e. array-constants) are entered in source as:
 
-	#( element1 element2 ... element-n)
+        #( element1 element2 ... element-N)
 
     where each element must be itself a literal constant.
     Array, symbol and byteArray constants within an array can be written
@@ -73,20 +72,40 @@
       #(nil true #true)       -> 3 elements: nil, true and a symbol (watch out)
       #(two [3 3 3] (4 4 4))  -> 3 elements: a symbol, a byteArray and another array
 
+    Also, a syntactic sugar piece allows for Array instances to be created dynamcially
+    at runtime with the brace syntax:
+
+        { expr1 . expr2 . ... . expr-N }
+
+    where each expr-i evaluates to an element of the new array instance.
+    Notice that the expressions are separated by a period.
+    Semantically, this is equivalent to ``Array with:expr1 with:expr2 ... with:expr-N''
+    Examples:
+        { 1 . 2 . 3 }         -> a new 3 element array; similar to #( 1 2 3 ),
+                                 but in contrast, a new array instance is created
+        { 
+            { 'foo' . [ Transcript showCR:'foo' ] } .
+            { 'bar' . [ Transcript showCR:'bar' ] } 
+            { 'baz' . [ Transcript showCR:'baz' ] } 
+        }                     
+                              -> a new 3 element array, consisting of 3 new
+                                 2-element array instances, consisting of a string
+                                 and a block each
+
     [memory requirements:]
-	OBJ-HEADER + (size * ptr-size)
+        OBJ-HEADER + (size * ptr-size)
 
     [warning:]
-	read the warning about 'growing fixed size collection'
-	in ArrayedCollection's documentation
+        read the warning about 'growing fixed size collection'
+        in ArrayedCollection's documentation
 
     [author:]
-	Claus Gittinger
+        Claus Gittinger
 
     [see also:]
-	OrderedCollection
-	ByteArray FloatArray DoubleArray
-	String
+        OrderedCollection
+        ByteArray FloatArray DoubleArray
+        String
 "
 ! !
 
@@ -2612,10 +2631,10 @@
 !Array class methodsFor:'documentation'!
 
 version
-    ^ '$Header: /cvs/stx/stx/libbasic/Array.st,v 1.162 2014-03-17 21:20:26 cg Exp $'
+    ^ '$Header: /cvs/stx/stx/libbasic/Array.st,v 1.163 2014-04-28 13:08:21 cg Exp $'
 !
 
 version_CVS
-    ^ '$Header: /cvs/stx/stx/libbasic/Array.st,v 1.162 2014-03-17 21:20:26 cg Exp $'
+    ^ '$Header: /cvs/stx/stx/libbasic/Array.st,v 1.163 2014-04-28 13:08:21 cg Exp $'
 ! !