From 2ffc7d7fd50aca5ab7e6339ec844d7b6d1cd5267 Mon Sep 17 00:00:00 2001 From: Michael McLoughlin Date: Thu, 27 Dec 2018 23:09:44 -0800 Subject: [PATCH] examples: add most docstrings --- examples/add/asm.go | 1 + examples/add/stub.go | 1 + examples/complex/asm.go | 17 ++++++++++------- examples/complex/complex.s | 14 +++++++------- examples/complex/complex_test.go | 12 ++++++------ examples/complex/stub.go | 9 ++++++--- examples/data/asm.go | 1 + examples/data/stub.go | 1 + examples/fnv1a/asm.go | 1 + examples/fnv1a/stub.go | 1 + examples/geohash/asm.go | 1 + examples/geohash/stub.go | 1 + examples/sha1/asm.go | 1 + examples/sha1/stub.go | 1 + examples/stadtx/asm.go | 1 + examples/stadtx/stub.go | 1 + examples/sum/asm.go | 1 + examples/sum/stub.go | 1 + 18 files changed, 43 insertions(+), 23 deletions(-) diff --git a/examples/add/asm.go b/examples/add/asm.go index 07c0f982..f869035f 100644 --- a/examples/add/asm.go +++ b/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) diff --git a/examples/add/stub.go b/examples/add/stub.go index a8054fce..6a9952a4 100644 --- a/examples/add/stub.go +++ b/examples/add/stub.go @@ -2,4 +2,5 @@ package add +// Add adds x and y. func Add(x uint64, y uint64) uint64 diff --git a/examples/complex/asm.go b/examples/complex/asm.go index f57ad1f4..1674e2ef 100644 --- a/examples/complex/asm.go +++ b/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) diff --git a/examples/complex/complex.s b/examples/complex/complex.s index b58af205..c1c18e6f 100644 --- a/examples/complex/complex.s +++ b/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 diff --git a/examples/complex/complex_test.go b/examples/complex/complex_test.go index 572c8311..9ffe8e03 100644 --- a/examples/complex/complex_test.go +++ b/examples/complex/complex_test.go @@ -9,8 +9,8 @@ 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) @@ -18,8 +18,8 @@ func TestReal(t *testing.T) { } 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) @@ -27,8 +27,8 @@ func TestImag(t *testing.T) { } 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) diff --git a/examples/complex/stub.go b/examples/complex/stub.go index 70929e29..0ff00b4e 100644 --- a/examples/complex/stub.go +++ b/examples/complex/stub.go @@ -2,8 +2,11 @@ package complex -func Real(x complex128) float64 +// Real returns the real part of z. +func Real(z complex128) float64 -func Imag(x complex128) float64 +// Imag returns the imaginary part of z. +func Imag(z complex128) float64 -func Norm(x complex128) float64 +// Norm returns the complex norm of z. +func Norm(z complex128) float64 diff --git a/examples/data/asm.go b/examples/data/asm.go index c1144ac8..91ff81a0 100644 --- a/examples/data/asm.go +++ b/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) diff --git a/examples/data/stub.go b/examples/data/stub.go index e3dfcbde..b787906f 100644 --- a/examples/data/stub.go +++ b/examples/data/stub.go @@ -2,4 +2,5 @@ package data +// DataAt returns byte i in the 'bytes' global data section. func DataAt(i int) byte diff --git a/examples/fnv1a/asm.go b/examples/fnv1a/asm.go index 8cd99fee..6e0615e4 100644 --- a/examples/fnv1a/asm.go +++ b/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()) diff --git a/examples/fnv1a/stub.go b/examples/fnv1a/stub.go index 2425a75a..c4f2d855 100644 --- a/examples/fnv1a/stub.go +++ b/examples/fnv1a/stub.go @@ -2,4 +2,5 @@ package fnv1a +// Hash64 computes the FNV-1a hash of data. func Hash64(data []byte) uint64 diff --git a/examples/geohash/asm.go b/examples/geohash/asm.go index 213baadb..05fea0aa 100644 --- a/examples/geohash/asm.go +++ b/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()) diff --git a/examples/geohash/stub.go b/examples/geohash/stub.go index 65ab94f8..f4314184 100644 --- a/examples/geohash/stub.go +++ b/examples/geohash/stub.go @@ -2,4 +2,5 @@ package geohash +// EncodeInt computes the 64-bit integer geohash of (lat, lng). func EncodeInt(lat float64, lng float64) uint64 diff --git a/examples/sha1/asm.go b/examples/sha1/asm.go index 92178176..1a35eb4d 100644 --- a/examples/sha1/asm.go +++ b/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())} diff --git a/examples/sha1/stub.go b/examples/sha1/stub.go index f51c0ec9..dba9934d 100644 --- a/examples/sha1/stub.go +++ b/examples/sha1/stub.go @@ -2,4 +2,5 @@ package sha1 +// block SHA-1 hashes the 64-byte message m into the running state h. func block(h *[5]uint32, m []byte) diff --git a/examples/stadtx/asm.go b/examples/stadtx/asm.go index 647473d0..f01175ab 100644 --- a/examples/stadtx/asm.go +++ b/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()) diff --git a/examples/stadtx/stub.go b/examples/stadtx/stub.go index 3dd60439..5630c57b 100644 --- a/examples/stadtx/stub.go +++ b/examples/stadtx/stub.go @@ -2,4 +2,5 @@ package stadtx +// Hash computes the Stadtx hash. func Hash(state *State, key []byte) uint64 diff --git a/examples/sum/asm.go b/examples/sum/asm.go index d0eb5610..f834e597 100644 --- a/examples/sum/asm.go +++ b/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() diff --git a/examples/sum/stub.go b/examples/sum/stub.go index d7bc64b0..ec014eeb 100644 --- a/examples/sum/stub.go +++ b/examples/sum/stub.go @@ -2,4 +2,5 @@ package sum +// Sum returns the sum of the elements in xs. func Sum(xs []uint64) uint64