support docstrings

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
 

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)
 }

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) }

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())

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

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()