- code document all enumarable functions and iterators in containers

stacks/arraystack/arraystack.go

@@ -101,20 +101,28 @@ type Iterator struct {
 	index int
 }
 
+// Returns a stateful iterator whose values can be fetched by an index.
 func (stack *Stack) Iterator() Iterator {
 	return Iterator{stack: stack, index: -1}
 }
 
+// Moves the iterator to the next element and returns true if there was a next element in the container.
+// If Next() returns true, then next element's index and value can be retrieved by Index() and Value().
+// Modifies the state of the iterator.
 func (iterator *Iterator) Next() bool {
 	iterator.index += 1
 	return iterator.stack.withinRange(iterator.index)
 }
 
+// Returns the current element's value.
+// Does not modify the state of the iterator.
 func (iterator *Iterator) Value() interface{} {
 	value, _ := iterator.stack.list.Get(iterator.stack.list.Size() - iterator.index - 1) // in reverse (LIFO)
 	return value
 }
 
+// Returns the current element's index.
+// Does not modify the state of the iterator.
 func (iterator *Iterator) Index() int {
 	return iterator.index
 }