examples: add most docstrings

examples/add/asm.go

@@ -8,6 +8,7 @@ import (
 
 func main() {
 	TEXT("Add", "func(x, y uint64) uint64")
+	Doc("Add adds x and y.")
 	x := Load(Param("x"), GP64v())
 	y := Load(Param("y"), GP64v())
 	ADDQ(x, y)

examples/complex/asm.go

@@ -7,19 +7,22 @@ import (
 )
 
 func main() {
-	TEXT("Real", "func(x complex128) float64")
-	r := Load(Param("x").Real(), Xv())
+	TEXT("Real", "func(z complex128) float64")
+	Doc("Real returns the real part of z.")
+	r := Load(Param("z").Real(), Xv())
 	Store(r, ReturnIndex(0))
 	RET()
 
-	TEXT("Imag", "func(x complex128) float64")
-	i := Load(Param("x").Imag(), Xv())
+	TEXT("Imag", "func(z complex128) float64")
+	Doc("Imag returns the imaginary part of z.")
+	i := Load(Param("z").Imag(), Xv())
 	Store(i, ReturnIndex(0))
 	RET()
 
-	TEXT("Norm", "func(x complex128) float64")
-	r = Load(Param("x").Real(), Xv())
-	i = Load(Param("x").Imag(), Xv())
+	TEXT("Norm", "func(z complex128) float64")
+	Doc("Norm returns the complex norm of z.")
+	r = Load(Param("z").Real(), Xv())
+	i = Load(Param("z").Imag(), Xv())
 	MULSD(r, r)
 	MULSD(i, i)
 	ADDSD(i, r)

examples/complex/complex.s

@@ -2,22 +2,22 @@
 
 #include "textflag.h"
 
-// func Real(x complex128) float64
+// func Real(z complex128) float64
 TEXT ·Real(SB), 0, $0-24
-	MOVSD	x_real(FP), X0
+	MOVSD	z_real(FP), X0
 	MOVSD	X0, ret+16(FP)
 	RET
 
-// func Imag(x complex128) float64
+// func Imag(z complex128) float64
 TEXT ·Imag(SB), 0, $0-24
-	MOVSD	x_imag+8(FP), X0
+	MOVSD	z_imag+8(FP), X0
 	MOVSD	X0, ret+16(FP)
 	RET
 
-// func Norm(x complex128) float64
+// func Norm(z complex128) float64
 TEXT ·Norm(SB), 0, $0-24
-	MOVSD	x_real(FP), X0
-	MOVSD	x_imag+8(FP), X1
+	MOVSD	z_real(FP), X0
+	MOVSD	z_imag+8(FP), X1
 	MULSD	X0, X0
 	MULSD	X1, X1
 	ADDSD	X1, X0

examples/complex/complex_test.go

@@ -9,26 +9,26 @@ import (
 //go:generate go run asm.go -out complex.s -stubs stub.go
 
 func TestReal(t *testing.T) {
-	expect := func(x complex128) float64 {
-		return real(x)
+	expect := func(z complex128) float64 {
+		return real(z)
 	}
 	if err := quick.CheckEqual(Real, expect, nil); err != nil {
 		t.Fatal(err)
 	}
 }
 
 func TestImag(t *testing.T) {
-	expect := func(x complex128) float64 {
-		return imag(x)
+	expect := func(z complex128) float64 {
+		return imag(z)
 	}
 	if err := quick.CheckEqual(Imag, expect, nil); err != nil {
 		t.Fatal(err)
 	}
 }
 
 func TestNorm(t *testing.T) {
-	expect := func(x complex128) float64 {
-		return math.Sqrt(real(x)*real(x) + imag(x)*imag(x))
+	expect := func(z complex128) float64 {
+		return math.Sqrt(real(z)*real(z) + imag(z)*imag(z))
 	}
 	if err := quick.CheckEqual(Norm, expect, nil); err != nil {
 		t.Fatal(err)

examples/data/asm.go

@@ -21,6 +21,7 @@ func main() {
 	DATA(39, U8(0x77))
 
 	TEXT("DataAt", "func(i int) byte")
+	Doc("DataAt returns byte i in the 'bytes' global data section.")
 	i := Load(Param("i"), GP64v())
 	ptr := Mem{Base: GP64v()}
 	LEAQ(bytes, ptr.Base)

examples/fnv1a/asm.go

@@ -15,6 +15,7 @@ const (
 
 func main() {
 	TEXT("Hash64", "func(data []byte) uint64")
+	Doc("Hash64 computes the FNV-1a hash of data.")
 	ptr := Load(Param("data").Base(), GP64v())
 	n := Load(Param("data").Len(), GP64v())
 

examples/geohash/asm.go

@@ -9,6 +9,7 @@ import (
 
 func main() {
 	TEXT("EncodeInt", "func(lat, lng float64) uint64")
+	Doc("EncodeInt computes the 64-bit integer geohash of (lat, lng).")
 	lat := Load(Param("lat"), Xv())
 	lng := Load(Param("lng"), Xv())
 

examples/sha1/asm.go

@@ -10,6 +10,7 @@ import (
 
 func main() {
 	TEXT("block", "func(h *[5]uint32, m []byte)")
+	Doc("block SHA-1 hashes the 64-byte message m into the running state h.")
 	h := Mem{Base: Load(Param("h"), GP64v())}
 	m := Mem{Base: Load(Param("m").Base(), GP64v())}
 

examples/stadtx/asm.go

@@ -39,6 +39,7 @@ func makelabels(name string, n int) []string {
 func main() {
 	Package("github.com/mmcloughlin/avo/examples/stadtx")
 	TEXT("Hash", "func(state *State, key []byte) uint64")
+	Doc("Hash computes the Stadtx hash.")
 
 	statePtr := Load(Param("state"), GP64v())
 	ptr := Load(Param("key").Base(), GP64v())

examples/sum/asm.go

@@ -9,6 +9,7 @@ import (
 
 func main() {
 	TEXT("Sum", "func(xs []uint64) uint64")
+	Doc("Sum returns the sum of the elements in xs.")
 	ptr := Load(Param("xs").Base(), GP64v())
 	n := Load(Param("xs").Len(), GP64v())
 	s := GP64v()