SampleGen: generate comments in output handling (#152)

Author: yihanzhen

cmd/gen-go-sample/gapic.go

@@ -62,6 +62,7 @@ type GAPICSample struct {
 }
 
 type OutputSpec struct {
+	Comment   []string
 	Define    string
 	Print     []string
 	Loop      *LoopSpec

cmd/gen-go-sample/main_test.go

@@ -62,6 +62,10 @@ func TestUnary(t *testing.T) {
 		OnSuccess: []OutputSpec{
 			{Define: "out_a = $resp.a"},
 			{Print: []string{"x = %s", "$resp.a.x"}},
+			{Comment: []string{
+				"%s contains the field %s,\n%%%% is a single percent,\nand '\\n' specifies a newline in comment too",
+				"out_a",
+				"y"}},
 			{Print: []string{"y = %s", "out_a.y"}},
 			{
 				Loop: &LoopSpec{

cmd/gen-go-sample/out.go

@@ -15,6 +15,7 @@
 package main
 
 import (
+	"bytes"
 	"fmt"
 	"strings"
 	"text/scanner"
@@ -101,6 +102,10 @@ func writeOutputSpec(out OutputSpec, st *symTab, gen *generator) error {
 		used++
 		err = writeDump(dp.FileName[0], dp.FileName[1:], dp.Contents, st, gen)
 	}
+	if c := out.Comment; len(c) > 0 {
+		used++
+		err = writeComment(c[0], c[1:], gen)
+	}
 
 	if used == 0 {
 		return errors.E(nil, "OutputSpec not defined")
@@ -252,6 +257,28 @@ func writeMap(l *LoopSpec, st *symTab, gen *generator) error {
 	return nil
 }
 
+func writeComment(cmtFmt string, cmtArgs []string, gen *generator) error {
+	var buf bytes.Buffer
+	args := make([]interface{}, len(cmtArgs))
+	for i := range cmtArgs {
+		args[i] = snakeToCamel(cmtArgs[i])
+	}
+
+	if _, err := fmt.Fprintf(&buf, cmtFmt, args...); err != nil {
+		return errors.E(err, "comment spec: bad format")
+	}
+	buf.WriteString("\n")
+	prependLines(&buf, "// ", false)
+	cmts := strings.Split(buf.String(), "\n")
+	for i, c := range(cmts) {
+		if i == len(cmts) - 1 {
+			continue
+		}
+		gen.pt.Printf(c)
+	}
+	return nil
+}
+
 func writePath(sc *scanner.Scanner, st *symTab, info pbinfo.Info) (string, initType, error) {
 	if sc.Scan() != scanner.Ident {
 		return "", initType{}, errors.E(nil, "expecting ident, got %s", sc.TokenText())

cmd/gen-go-sample/testdata/sample_unary.want

@@ -80,6 +80,9 @@ func sampleUnaryMethod(theX int64, theB string, theFoo string, bobFile string) e
 
 	outA := resp.GetA()
 	fmt.Printf("x = %v\n", resp.GetA().GetX())
+	// outA contains the field y,
+	// % is a single percent,
+	// and '\n' specifies a newline in comment too
 	fmt.Printf("y = %v\n", outA.GetY())
 	for _, r := range resp.GetR() {
 		fmt.Printf("resp.r contains %v\n", r)