--- a/SegmentedOrderedCollection.st	Wed Mar 20 12:27:53 2013 +0100
+++ b/SegmentedOrderedCollection.st	Wed Mar 20 12:31:48 2013 +0100
@@ -48,6 +48,8 @@
 !SegmentedOrderedCollection methodsFor:'accessing'!
 
 at:index
+    "return the element at index, anInteger"
+
     |segStart segEnd|
 
     (index between:1 and:tally) ifFalse:[
@@ -65,6 +67,9 @@
 !
 
 at:index put:newElement
+    "set the element at index, to be anInteger.
+     Return anObject (sigh)."
+
     |segStart segEnd|
 
     (index between:1 and:tally) ifFalse:[
@@ -83,11 +88,15 @@
 !
 
 first
+    "return the first element"
+
     tally == 0 ifTrue:[^ self emptyCollectionError].
     ^ segments first first
 !
 
 last
+    "return the last element"
+
     tally == 0 ifTrue:[^ self emptyCollectionError].
     ^ segments last last
 ! !
@@ -159,6 +168,9 @@
 !
 
 removeFirst
+    "remove the first element from the collection; return the element.
+     If there is no element in the receiver collection, raise an error."
+
     |seg el|
 
     tally == 0 ifTrue:[
@@ -174,6 +186,13 @@
 !
 
 removeFromIndex:startIndex toIndex:endIndex
+    "remove the elements stored under startIndex up to and including
+     the elements under stopIndex.
+     Return the receiver.
+     Returning the receiver here is a historic leftover - it may change.
+     Please use yourself in a cascade, if you need the receiver's value
+     when using this method."
+
     |segStart segEnd removing segIndex nextSegIndex seg|
 
     (startIndex between:1 and:tally) ifFalse:[
@@ -231,6 +250,8 @@
 !
 
 removeLast
+    "remove the last element from the collection; return the element"
+
     |seg el|
 
     tally == 0 ifTrue:[
@@ -243,31 +264,22 @@
     ].
     tally := tally - 1.
     ^ el
-!
-
-splitSegmentAt:segmentIndex
-    |seg rightPart|
-
-    seg := segments at:segmentIndex.
-
-    rightPart := OrderedCollection new:20.
-    rightPart grow:10.
-    rightPart replaceFrom:1 to:10 with:seg startingAt:(seg size - 9).
-
-    seg removeFromIndex:(seg size - 9) toIndex:seg size.
-
-    segments add:rightPart afterIndex:segmentIndex.
 ! !
 
 !SegmentedOrderedCollection methodsFor:'enumerating'!
 
 do:aBlock
+    "evaluate the argument, aBlock for every element in the collection."
+
     segments do:[:seg |
         seg do:aBlock
     ].
 !
 
 keysAndValuesDo:aBlock
+    "evaluate the argument, aBlock for every element in the collection,
+     passing both index and element as arguments."
+
     |idx|
 
     idx := 1.
@@ -329,19 +341,37 @@
     tally := 0.
 ! !
 
+!SegmentedOrderedCollection methodsFor:'private'!
+
+splitSegmentAt:segmentIndex
+    |seg rightPart|
+
+    seg := segments at:segmentIndex.
+
+    rightPart := OrderedCollection new:20.
+    rightPart grow:10.
+    rightPart replaceFrom:1 to:10 with:seg startingAt:(seg size - 9).
+
+    seg removeFromIndex:(seg size - 9) toIndex:seg size.
+
+    segments add:rightPart afterIndex:segmentIndex.
+! !
+
 !SegmentedOrderedCollection methodsFor:'queries'!
 
 size
+    "return the number of elements in the collection"
+
     ^ tally
 ! !
 
 !SegmentedOrderedCollection class methodsFor:'documentation'!
 
 version
-    ^ '$Header: /cvs/stx/stx/libbasic2/SegmentedOrderedCollection.st,v 1.3 2013-03-20 11:27:53 cg Exp $'
+    ^ '$Header: /cvs/stx/stx/libbasic2/SegmentedOrderedCollection.st,v 1.4 2013-03-20 11:31:48 cg Exp $'
 !
 
 version_CVS
-    ^ '$Header: /cvs/stx/stx/libbasic2/SegmentedOrderedCollection.st,v 1.3 2013-03-20 11:27:53 cg Exp $'
+    ^ '$Header: /cvs/stx/stx/libbasic2/SegmentedOrderedCollection.st,v 1.4 2013-03-20 11:31:48 cg Exp $'
 ! !