- documentation updates

README.md

@@ -33,6 +33,7 @@ Implementation of various data structures and algorithms in Go.
       - [EnumerableWithKey](#enumerablewithkey)
     - [Sort](#sort)
     - [Container](#container)
+- [Appendix](#appendix)
 
 
 ## Containers
@@ -48,9 +49,9 @@ type Container interface {
 }
 ```
 
-Containers are either ordered or unordered. All ordered containers provide [stateful iterators](iterator) and some of them allow [enumerable functions](#enumerable).
+Containers are either ordered or unordered. All ordered containers provide [stateful iterators](#iterator) and some of them allow [enumerable functions](#enumerable).
 
-| Container | Ordered | [Iterator](iterator) | [Enumerable](#enumerable) | Ordered by |
+| Container | Ordered | [Iterator](#iterator) | [Enumerable](#enumerable) | Ordered by |
 | :--- | :---: | :---: | :---: | :---: |
 | [ArrayList](#arraylist) | yes | yes | yes | index |
 | [SinglyLinkedList](#singlylinkedlist) | yes | yes | yes | index |
@@ -641,7 +642,7 @@ func main() {
 
 ### Iterator
 
-All ordered containers have stateful iterators. Typically an iterator is obtained by _Iterator()_ function of an ordered container. Once obtained, iterator's _Next()_ function moves the iterator to the next element and returns true if there was a next element. If there was an element, then element's can be obtained by iterator's _Value()_ function. Depending on the ordering type, it's position can be obtained by iterator's _Index()_ or _Key()_ functions. '
+All ordered containers have stateful iterators. Typically an iterator is obtained by _Iterator()_ function of an ordered container. Once obtained, iterator's _Next()_ function moves the iterator to the next element and returns true if there was a next element. If there was an element, then element's can be obtained by iterator's _Value()_ function. Depending on the ordering type, it's position can be obtained by iterator's _Index()_ or _Key()_ functions.
 
 #### IteratorWithIndex
 
@@ -673,68 +674,92 @@ Enumerable functions for ordered containers that implement [EnumerableWithIndex]
 
 #### EnumerableWithIndex
 
-Enumerable function for ordered containers whose values can be fetched by an index.
+[Enumerable](#enumerable) functions for ordered containers whose values can be fetched by an index.
 
-Definition:
+**Each**: Calls the given function once for each element, passing that element's index and value.
 
 ```go
-type EnumerableWithIndex interface {
-	// Calls the given function once for each element, passing that element's index and value.
 Each(func(index int, value interface{}))
+```
 
-	// Invokes the given function once for each element and returns a
+**Map**: Invokes the given function once for each element and returns a container containing the values returned by the given function.
-	// container containing the values returned by the given function.
+
+```go
 Map(func(index int, value interface{}) interface{}) Container
+```
 
-	// Returns a new container containing all elements for which the given function returns a true value.
+**Select**: Returns a new container containing all elements for which the given function returns a true value.
+
+```go
 Select(func(index int, value interface{}) bool) Container
+```
 
-	// Passes each element of the container to the given function and
+**Any**: Passes each element of the container to the given function and returns true if the function ever returns true for any element.
-	// returns true if the function ever returns true for any element.
+
+```go
 Any(func(index int, value interface{}) bool) bool
+```
 
-	// Passes each element of the container to the given function and
+**All**: Passes each element of the container to the given function and returns true if the function returns true for all elements.
-	// returns true if the function returns true for all elements.
+
+```go
 All(func(index int, value interface{}) bool) bool
+```
 
-	// Passes each element of the container to the given function and returns
+**Find**: Passes each element of the container to the given function and returns the first (index,value) for which the function is true or -1,nil otherwise if no element matches the criteria.
-	// the first (index,value) for which the function is true or -1,nil otherwise
+
-	// if no element matches the criteria.
+```go
-	Find(func(index int, value interface{}) bool) (int, interface{})
+Find(func(index int, value interface{}) bool) (int, interface{})}
-}
+```
+
+Typical usage:
+```go
+TODO
 ```
 
 #### EnumerableWithKey
 
 Enumerable functions for ordered containers whose values whose elements are key/value pairs.
 
-Definition: 
+**Each**: Calls the given function once for each element, passing that element's key and value.
 
 ```go
-type EnumerableWithKey interface {
-	// Calls the given function once for each element, passing that element's key and value.
 Each(func(key interface{}, value interface{}))
+```
 
-	// Invokes the given function once for each element and returns a container
+**Map**: Invokes the given function once for each element and returns a container containing the values returned by the given function as key/value pairs.
-	// containing the values returned by the given function as key/value pairs.
+
+```go
 Map(func(key interface{}, value interface{}) (interface{}, interface{})) Container
+```
 
-	// Returns a new container containing all elements for which the given function returns a true value.
+**Select**: Returns a new container containing all elements for which the given function returns a true value.
+
+```go
 Select(func(key interface{}, value interface{}) bool) Container
+```
 
-	// Passes each element of the container to the given function and
+**Any**: Passes each element of the container to the given function and returns true if the function ever returns true for any element.
-	// returns true if the function ever returns true for any element.
+
+```go
 Any(func(key interface{}, value interface{}) bool) bool
+```
 
-	// Passes each element of the container to the given function and
+**All**: Passes each element of the container to the given function and returns true if the function returns true for all elements.
-	// returns true if the function returns true for all elements.
+
+```go
 All(func(key interface{}, value interface{}) bool) bool
+```
 
-	// Passes each element of the container to the given function and returns
+**Find**: Passes each element of the container to the given function and returns the first (key,value) for which the function is true or nil,nil otherwise if no element matches the criteria.
-	// the first (key,value) for which the function is true or nil,nil otherwise if no element
+
-	// matches the criteria.
+```go
 Find(func(key interface{}, value interface{}) bool) (interface{}, interface{})
-}
+```
+
+Typical usage:
+```go
+TODO
 ```
 
 ### Sort
@@ -772,8 +797,18 @@ func GetSortedValues(container Container, comparator utils.Comparator) []interfa
 Usage:
 
 ```go
+package main
+
+import (
+	"github.com/emirpasic/gods/lists/arraylist"
+    "github.com/emirpasic/gods/utils"
+)
+
+func main() {
+	list := arraylist.New()
     list.Add(2, 1, 3)
     values := GetSortedValues(container, utils.StringComparator) // [1, 2, 3]
+}
 ```
 
 ## Appendix

containers/enumerable.go

@@ -29,7 +29,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 package containers
 
-// Enumerable function for ordered containers whose values can be fetched by an index.
+// Enumerable functions for ordered containers whose values can be fetched by an index.
 type EnumerableWithIndex interface {
 	// Calls the given function once for each element, passing that element's index and value.
 	Each(func(index int, value interface{}))
@@ -55,7 +55,7 @@ type EnumerableWithIndex interface {
 	Find(func(index int, value interface{}) bool) (int, interface{})
 }
 
-// Enumerable function for ordered containers whose values whose elements are key value pairs.
+// Enumerable functions for ordered containers whose values whose elements are key/value pairs.
 type EnumerableWithKey interface {
 	// Calls the given function once for each element, passing that element's key and value.
 	Each(func(key interface{}, value interface{}))