From fdbea4bd277c6d4b186ba602b551a3ff041990d6 Mon Sep 17 00:00:00 2001
From: emirpasic <emirpasic@hotmail.com>
Date: Sat, 7 Mar 2015 17:20:31 +0100
Subject: [PATCH] - documentation for arraylist

---
 README.md | 54 +++++++++++++++++++++++++++++++-----------------------
 1 file changed, 31 insertions(+), 23 deletions(-)

diff --git a/README.md b/README.md
index 706066c..e1948d7 100644
--- a/README.md
+++ b/README.md
@@ -99,36 +99,44 @@ func main() {
 
 ###Lists
 
-####ArrayList
+A list is a data structure that can store elements and may have repeated values. There is no ordering in a list. The user can access and remove an element by the index position.
 
-```go
-package main
+All lists implement the list interface with the following methods:
 
-import "github.com/emirpasic/gods/lists/arraylist"
-
-func main() {
-	list := arraylist.New()
-
-	list.Add("a")      // ["a"]
-	list.Add("b", "c") // ["a","b","c"]
-
-	_, _ = list.Get(0)   // "a",true
-	_, _ = list.Get(100) // nil,false
+```go
+	Get(index int) (interface{}, bool)
+	Remove(index int)
+	Add(elements ...interface{})
+	Contains(elements ...interface{}) bool
+	Empty() bool
+	Size() int
+	Clear()
+	Values() []interface{}
+```
 
-	_ = list.Contains("a", "b", "c")      //true
-	_ = list.Contains("a", "b", "c", "d") //false
+####ArrayList
 
-	list.Remove(2) // ["a","b"]
-	list.Remove(1) // ["a"]
-	list.Remove(0) // []
-	list.Remove(0) // [] (ignored)
+This structure implements the List interface and is backed by a dynamic array that grows and shrinks implicitly (by 50% when capacity is reached).
 
-	_ = list.Empty() // true
-	_ = list.Size()  // 0
+Direct access method _Get(index)_ is guaranteed a constant time performance. Remove is of linear time performance. Checking with _Contains()_ is of quadratic complexity.
 
-	list.Add("a") // ["a"]
-	list.Clear()  // []
 
+```go
+	list := arraylist.New()
+	list.Add("a")                         // ["a"]
+	list.Add("b", "c")                    // ["a","b","c"]
+	_, _ = list.Get(0)                    // "a",true
+	_, _ = list.Get(100)                  // nil,false
+	_ = list.Contains("a", "b", "c")      // true
+	_ = list.Contains("a", "b", "c", "d") // false
+	list.Remove(2)                        // ["a","b"]
+	list.Remove(1)                        // ["a"]
+	list.Remove(0)                        // []
+	list.Remove(0)                        // [] (ignored)
+	_ = list.Empty()                      // true
+	_ = list.Size()                       // 0
+	list.Add("a")                         // ["a"]
+	list.Clear()                          // []
 }
 ```