more docs

Author: Nithin Chintala

README.md

@@ -22,20 +22,55 @@ later time. Wikipedia also has a [summary](https://en.wikipedia.org/wiki/Memory_
 ## Example
 ![](amalloc.gif)
 
+## Usage
+```
+usage: amalloc [-speed={step|slow|norm|fast|inst}]
+  -speed The time between each frame in the animation
+      step: wait for user input
+      slow: wait 1.5s
+      norm: wait 1.0s (default)
+      fast: wait 0.5s
+      inst: wait 0.0s
+```
+Once you are running the code the following commands are valid. To keep
+the animation less crowded, variables are limited to single characters.
+```
+>>> <char> = malloc(<size>)
+>>> free(<char>)
+
+>>> x = malloc(4)
+>>> y = malloc(7)
+>>> free(x)
+>>> free(y)
+```
+
 ## Install
 You can build the executable
 ```
-$ git clone https://github.com/NithinChintala/amalloc.git
+$ git clone https://github.com/NithinChintala/amalloc.git && cd amalloc
 $ go build
 $ ./amalloc
 ```
 Or run it as a script
 ```
-$ git clone https://github.com/NithinChintala/amalloc.git
+$ git clone https://github.com/NithinChintala/amalloc.git && cd amalloc
 $ go run main.go
 ```
 
 # How Does it Work?
+At a high level the code is running a Finite State Machine. Each state is
+rendered in the animation and calling malloc / free alters the state of
+the animation. For all the transitions see below. You always start in the
+Idle state and wait for some user input. All other states go on to the 
+next state based on the input speed. The animation will always show what
+state is currently being rendered.
+![](fsm.png)
+
+
+These are the ways the headers and cells are represented. The next and prev
+sections represent indexes each byte in the 16 byte heap. Since it takes
+4 bits to represent 16 location, a NULL pointer is represented as 11111 or
+5 ones in a row.
 **Header** - 1 byte
 ```
          used         unused
@@ -64,5 +99,3 @@ $ go run main.go
 
 [0b00111111, 0b00000100] == {used: false, index: 1, prev: 31, next: 4}
 ```
-
-![](fsm.png)

fsm.png

@@ -15,7 +15,6 @@ func (dn *DevNull) Write(p []byte) (n int, err error) { return 0, nil }
 
 func main() {
 	interact()
-	//debug()
 }
 
 func interact() {

main.go

@@ -213,7 +213,6 @@ func Anim(h *Heap, waitFunc func()) {
 	reader := bufio.NewReader(os.Stdin)
 	for {
 		Render(h)
-		//fmt.Printf("\n%sState: %s\nCount: %d\n%v\n>>> ", ClearEnd, h.getPrevState(), count, h)
 		fmt.Printf("\n%sState: %s\nCount: %d\n>>> ", ClearEnd, h.getPrevState(), count)
 		count++
 		if h.prevState[Type] == Idle && h.state[Type] == Idle {