diff --git a/ast.go b/ast.go index 9b62aff..c228405 100644 --- a/ast.go +++ b/ast.go @@ -118,6 +118,7 @@ func (f *File) Functions() []*Function { // Function represents an assembly function. type Function struct { Name string + Doc []string Signature *gotypes.Signature LocalSize int diff --git a/build/context.go b/build/context.go index 2df2179..237d090 100644 --- a/build/context.go +++ b/build/context.go @@ -51,6 +51,10 @@ func (c *Context) Function(name string) { c.file.AddSection(c.function) } +func (c *Context) Doc(lines ...string) { + c.activefunc().Doc = lines +} + func (c *Context) Signature(s *gotypes.Signature) { c.activefunc().SetSignature(s) } diff --git a/build/global.go b/build/global.go index 0c3fdbc..d665333 100644 --- a/build/global.go +++ b/build/global.go @@ -57,6 +57,8 @@ func ReturnIndex(i int) gotypes.Component { return ctx.ReturnIndex(i) } func Load(src gotypes.Component, dst reg.Register) reg.Register { return ctx.Load(src, dst) } func Store(src reg.Register, dst gotypes.Component) { ctx.Store(src, dst) } +func Doc(lines ...string) { ctx.Doc(lines...) } + func AllocLocal(size int) operand.Mem { return ctx.AllocLocal(size) } func ConstData(name string, v operand.Constant) operand.Mem { return ctx.ConstData(name, v) } diff --git a/examples/returns/asm.go b/examples/returns/asm.go index a3b8623..d512c17 100644 --- a/examples/returns/asm.go +++ b/examples/returns/asm.go @@ -10,8 +10,11 @@ import ( func main() { Package("github.com/mmcloughlin/avo/examples/returns") - // Multiple unnamed return values. TEXT("Interval", "func(start, size uint64) (uint64, uint64)") + Doc( + "Interval returns the (start, end) of an interval with the given start and size.", + "Demonstrates multiple unnamed return values.", + ) start := Load(Param("start"), GP64v()) size := Load(Param("size"), GP64v()) end := size @@ -20,8 +23,11 @@ func main() { Store(end, ReturnIndex(1)) RET() - // Butterfly demonstrates multiple named return values. TEXT("Butterfly", "func(x0, x1 float64) (y0, y1 float64)") + Doc( + "Butterfly performs a 2-dimensional butterfly operation: computes (x0+x1, x0-x1).", + "Demonstrates multiple named return values.", + ) x0 := Load(Param("x0"), Xv()) x1 := Load(Param("x1"), Xv()) y0, y1 := Xv(), Xv() @@ -33,16 +39,22 @@ func main() { Store(y1, Return("y1")) RET() - // Septuple returns an array of seven of the given byte. TEXT("Septuple", "func(byte) [7]byte") + Doc( + "Septuple returns an array of seven of the given byte.", + "Demonstrates returning array values.", + ) b := Load(ParamIndex(0), GP8v()) for i := 0; i < 7; i++ { Store(b, ReturnIndex(0).Index(i)) } RET() - // CriticalLine returns the complex value 0.5 + it on Riemann's critical line. TEXT("CriticalLine", "func(t float64) complex128") + Doc( + "CriticalLine returns the complex value 0.5 + it on Riemann's critical line.", + "Demonstrates returning complex values.", + ) t := Load(Param("t"), Xv()) half := Xv() MOVSD(ConstData("half", F64(0.5)), half) @@ -50,8 +62,11 @@ func main() { Store(t, ReturnIndex(0).Imag()) RET() - // NewStruct initializes a Struct value. TEXT("NewStruct", "func(w uint16, p [2]float64, q uint64) Struct") + Doc( + "NewStruct initializes a Struct value.", + "Demonstrates returning struct values.", + ) w := Load(Param("w"), GP16v()) x := Load(Param("p").Index(0), Xv()) y := Load(Param("p").Index(1), Xv()) diff --git a/examples/returns/stub.go b/examples/returns/stub.go index 6988403..7a27f1b 100644 --- a/examples/returns/stub.go +++ b/examples/returns/stub.go @@ -2,12 +2,22 @@ package returns +// Interval returns the (start, end) of an interval with the given start and size. +// Demonstrates multiple unnamed return values. func Interval(start uint64, size uint64) (uint64, uint64) +// Butterfly performs a 2-dimensional butterfly operation: computes (x0+x1, x0-x1). +// Demonstrates multiple named return values. func Butterfly(x0 float64, x1 float64) (y0 float64, y1 float64) +// Septuple returns an array of seven of the given byte. +// Demonstrates returning array values. func Septuple(byte) [7]byte +// CriticalLine returns the complex value 0.5 + it on Riemann's critical line. +// Demonstrates returning complex values. func CriticalLine(t float64) complex128 +// NewStruct initializes a Struct value. +// Demonstrates returning struct values. func NewStruct(w uint16, p [2]float64, q uint64) Struct diff --git a/printer/stubs.go b/printer/stubs.go index 7a25332..75b5fb1 100644 --- a/printer/stubs.go +++ b/printer/stubs.go @@ -20,6 +20,7 @@ func (s *stubs) Print(f *avo.File) ([]byte, error) { s.Printf("package %s\n", s.cfg.Pkg) for _, fn := range f.Functions() { s.NL() + s.Comment(fn.Doc...) s.Printf("%s\n", fn.Stub()) } return s.Result()