doc,examples/sum: improve doc on sum example

Updates #13

README.md

@@ -103,15 +103,25 @@ func main() {
 	Doc("Sum returns the sum of the elements in xs.")
 	ptr := Load(Param("xs").Base(), GP64())
 	n := Load(Param("xs").Len(), GP64())
+
+	// Initialize sum register to zero.
 	s := GP64()
 	XORQ(s, s)
+
+	// Loop until zero bytes remain.
 	Label("loop")
 	CMPQ(n, Imm(0))
 	JE(LabelRef("done"))
+
+	// Load from pointer and add to running sum.
 	ADDQ(Mem{Base: ptr}, s)
+
+	// Advance pointer, decrement byte count.
 	ADDQ(Imm(8), ptr)
 	DECQ(n)
 	JMP(LabelRef("loop"))
+
+	// Store sum to return value.
 	Label("done")
 	Store(s, ReturnIndex(0))
 	RET()
@@ -119,6 +129,31 @@ func main() {
 }
 ```
 
+The result from this code generator is:
+
+[embedmd]:# (examples/sum/sum.s)
+```s
+// Code generated by command: go run asm.go -out sum.s -stubs stub.go. DO NOT EDIT.
+
+// func Sum(xs []uint64) uint64
+TEXT ·Sum(SB), $0-32
+	MOVQ	xs_base(FP), AX
+	MOVQ	xs_len+8(FP), CX
+	XORQ	DX, DX
+loop:
+	CMPQ	CX, $0x00
+	JE	done
+	ADDQ	(AX), DX
+	ADDQ	$0x08, AX
+	DECQ	CX
+	JMP	loop
+done:
+	MOVQ	DX, ret+24(FP)
+	RET
+```
+
+Full example at [`examples/sum`](examples/sum).
+
 ### Parameter Load/Store
 
 `avo` provides deconstruction of complex data datatypes into components. For example, load the length of a string argument with:

examples/sum/README.md

@@ -9,15 +9,25 @@ func main() {
 	Doc("Sum returns the sum of the elements in xs.")
 	ptr := Load(Param("xs").Base(), GP64())
 	n := Load(Param("xs").Len(), GP64())
+
+	// Initialize sum register to zero.
 	s := GP64()
 	XORQ(s, s)
+
+	// Loop until zero bytes remain.
 	Label("loop")
 	CMPQ(n, Imm(0))
 	JE(LabelRef("done"))
+
+	// Load from pointer and add to running sum.
 	ADDQ(Mem{Base: ptr}, s)
+
+	// Advance pointer, decrement byte count.
 	ADDQ(Imm(8), ptr)
 	DECQ(n)
 	JMP(LabelRef("loop"))
+
+	// Store sum to return value.
 	Label("done")
 	Store(s, ReturnIndex(0))
 	RET()

examples/sum/asm.go

@@ -12,15 +12,25 @@ func main() {
 	Doc("Sum returns the sum of the elements in xs.")
 	ptr := Load(Param("xs").Base(), GP64())
 	n := Load(Param("xs").Len(), GP64())
+
+	// Initialize sum register to zero.
 	s := GP64()
 	XORQ(s, s)
+
+	// Loop until zero bytes remain.
 	Label("loop")
 	CMPQ(n, Imm(0))
 	JE(LabelRef("done"))
+
+	// Load from pointer and add to running sum.
 	ADDQ(Mem{Base: ptr}, s)
+
+	// Advance pointer, decrement byte count.
 	ADDQ(Imm(8), ptr)
 	DECQ(n)
 	JMP(LabelRef("loop"))
+
+	// Store sum to return value.
 	Label("done")
 	Store(s, ReturnIndex(0))
 	RET()