--- a/CharacterWriteStream.st	Mon Apr 25 16:07:36 2016 +0200
+++ b/CharacterWriteStream.st	Mon Apr 25 16:14:00 2016 +0200
@@ -1,5 +1,3 @@
-"{ Encoding: utf8 }"
-
 "
  COPYRIGHT (c) 2005 by eXept Software AG
               All Rights Reserved
@@ -88,7 +86,7 @@
 !CharacterWriteStream methodsFor:'accessing'!
 
 reset
-    "reset the stream; write anew.
+    "reset the stream, to write again over the existing (or already written) contents.
      See the comment in WriteStream>>contents"
 
     collection := String new:collection size.
@@ -117,18 +115,47 @@
 !CharacterWriteStream methodsFor:'private-accessing'!
 
 on:aCollection
+    "return a stream for writing into aCollection"
+    
     currentCharacterSize := aCollection bitsPerCharacter.
     ^ super on:aCollection.
 !
 
 on:aCollection from:start to:stop
+    "return a stream for writing into part of aCollection.
+     This will position the stream to start writing at start-index,
+     and setup a writeLimit at stop-index.
+     Contents after stop-index will not be overwritten."
+
     currentCharacterSize := aCollection bitsPerCharacter.
     ^ super on:aCollection from:start to:stop.
+
+    "notice: only the first 6 characters are overwritten:
+    
+     |str s|
+     str := 'hello world bla'.
+     s := CharacterWriteStream on:str from:6 to:11.
+     s nextPutAll:'1234567890'.
+     str
+    "
 !
 
 with:aCollection
+    "return a stream for writing into aCollection.
+     This will position the stream to the end, and append written elements
+     after the initial contents.
+     I.e. the effect is similar to creating an empty stream first and then write
+     aCollection."
+
     currentCharacterSize := aCollection bitsPerCharacter.
     ^ super with:aCollection.
+
+    "
+     |s|
+     s := CharacterWriteStream with:'hello'.
+     s nextPutAll:'1234567890'.
+     s contents
+    "
 ! !
 
 !CharacterWriteStream methodsFor:'writing'!