From 2c5fb4e13356f7de2e004573b46a0fcf624c1bb5 Mon Sep 17 00:00:00 2001 From: gak Date: Thu, 16 May 2024 12:04:47 +1000 Subject: [PATCH] fix: generate comments in module scaffolds #1489 (part 1) (#1501) --- buildengine/build_go_test.go | 36 +++++++++++++++---- go-runtime/compile/build.go | 13 ++++--- .../external_module.go | 19 +++++++--- 3 files changed, 53 insertions(+), 15 deletions(-) diff --git a/buildengine/build_go_test.go b/buildengine/build_go_test.go index f3c4a58f0b..e7527a357c 100644 --- a/buildengine/build_go_test.go +++ b/buildengine/build_go_test.go @@ -17,9 +17,10 @@ func TestGenerateGoModule(t *testing.T) { schema.Builtins(), {Name: "other", Decls: []schema.Decl{ &schema.Enum{ - Name: "Color", - Export: true, - Type: &schema.String{}, + Comments: []string{"This is an enum.", "", "It has 3 variants."}, + Name: "Color", + Export: true, + Type: &schema.String{}, Variants: []*schema.EnumVariant{ {Name: "Red", Value: &schema.StringValue{Value: "Red"}}, {Name: "Blue", Value: &schema.StringValue{Value: "Blue"}}, @@ -37,15 +38,18 @@ func TestGenerateGoModule(t *testing.T) { }, }, &schema.Enum{ - Name: "TypeEnum", - Export: true, + Comments: []string{"This is type enum."}, + Name: "TypeEnum", + Export: true, Variants: []*schema.EnumVariant{ {Name: "A", Value: &schema.TypeValue{Value: &schema.Int{}}}, {Name: "B", Value: &schema.TypeValue{Value: &schema.String{}}}, }, }, &schema.Data{Name: "EchoRequest", Export: true}, - &schema.Data{Name: "EchoResponse", Export: true}, + &schema.Data{ + Comments: []string{"This is an echo data response."}, + Name: "EchoResponse", Export: true}, &schema.Verb{ Name: "echo", Export: true, @@ -54,6 +58,7 @@ func TestGenerateGoModule(t *testing.T) { }, &schema.Data{Name: "SinkReq", Export: true}, &schema.Verb{ + Comments: []string{"This is a sink verb.", "", "Here is another line for this comment!"}, Name: "sink", Export: true, Request: &schema.Ref{Name: "SinkReq"}, @@ -86,6 +91,10 @@ import ( var _ = context.Background +// This is an enum. +// +// It has 3 variants. +// //ftl:enum type Color string const ( @@ -102,6 +111,8 @@ const ( GreenInt ColorInt = 2 ) +// This is type enum. +// //ftl:enum type TypeEnum interface { typeEnum() } @@ -116,6 +127,7 @@ func (B) typeEnum() {} type EchoRequest struct { } +// This is an echo data response. type EchoResponse struct { } @@ -127,6 +139,10 @@ func Echo(context.Context, EchoRequest) (EchoResponse, error) { type SinkReq struct { } +// This is a sink verb. +// +// Here is another line for this comment! +// //ftl:verb func Sink(context.Context, SinkReq) error { panic("Verb stubs should not be called directly, instead use github.com/TBD54566975/ftl/runtime-go/ftl.CallSink()") @@ -175,9 +191,12 @@ func TestMetadataImportsExcluded(t *testing.T) { Modules: []*schema.Module{ schema.Builtins(), {Name: "test", Decls: []schema.Decl{ - &schema.Data{Name: "Req", Export: true}, + &schema.Data{ + Comments: []string{"Request data type."}, + Name: "Req", Export: true}, &schema.Data{Name: "Resp", Export: true}, &schema.Verb{ + Comments: []string{"This is a verb."}, Name: "call", Export: true, Request: &schema.Ref{Name: "Req"}, @@ -199,12 +218,15 @@ import ( var _ = context.Background +// Request data type. type Req struct { } type Resp struct { } +// This is a verb. +// //ftl:verb func Call(context.Context, Req) (Resp, error) { panic("Verb stubs should not be called directly, instead use github.com/TBD54566975/ftl/runtime-go/ftl.Call()") diff --git a/go-runtime/compile/build.go b/go-runtime/compile/build.go index 42f685d155..f0afcdd384 100644 --- a/go-runtime/compile/build.go +++ b/go-runtime/compile/build.go @@ -30,6 +30,7 @@ import ( "github.com/TBD54566975/ftl/internal/exec" "github.com/TBD54566975/ftl/internal/log" "github.com/TBD54566975/ftl/internal/reflect" + islices "github.com/TBD54566975/ftl/internal/slices" ) type ExternalModuleContext struct { @@ -261,10 +262,14 @@ func online() bool { var scaffoldFuncs = scaffolder.FuncMap{ "comment": func(s []string) string { - if len(s) == 0 { - return "" - } - return "// " + strings.Join(s, "\n// ") + return strings.Join(islices.Map(s, func(line string) string { + commented := "//" + // Prevent trailing whitespace on empty lines. + if line != "" { + commented += " " + line + } + return commented + }), "\n") }, "type": genType, "is": func(kind string, t schema.Node) bool { diff --git a/go-runtime/compile/external-module-template/_ftl/go/modules/{{ range .NonMainModules }}{{ push .Name . }}{{ end }}/external_module.go b/go-runtime/compile/external-module-template/_ftl/go/modules/{{ range .NonMainModules }}{{ push .Name . }}{{ end }}/external_module.go index 2cd9aefb09..a25872b21b 100644 --- a/go-runtime/compile/external-module-template/_ftl/go/modules/{{ range .NonMainModules }}{{ push .Name . }}{{ end }}/external_module.go +++ b/go-runtime/compile/external-module-template/_ftl/go/modules/{{ range .NonMainModules }}{{ push .Name . }}{{ end }}/external_module.go @@ -15,6 +15,10 @@ var _ = context.Background {{- if .IsExported}} {{if and (is "Enum" .) .IsValueEnum}} {{$enumName := .Name -}} +{{if .Comments -}} +{{.Comments|comment}} +// +{{end -}} //ftl:enum type {{.Name|title}} {{type $ .Type}} const ( @@ -23,6 +27,9 @@ const ( {{- end}} ) {{- else if is "Enum" . }} +{{.Comments|comment}} +{{if .Comments}}// +{{end -}} //ftl:enum {{$enumInterfaceFuncName := enumInterfaceFunc . -}} type {{.Name|title}} interface { {{$enumInterfaceFuncName}}() } @@ -32,7 +39,10 @@ type {{.Name|title}} {{type $ .Value.Value}} {{end}} func ({{.Name|title}}) {{$enumInterfaceFuncName}}() {} {{- end}} -{{- else if is "Data" . }} +{{- else if is "Data" .}} +{{if .Comments -}} +{{.Comments|comment}} +{{end -}} type {{.Name|title}} {{- if .TypeParameters}}[ {{- range $i, $tp := .TypeParameters}} @@ -43,9 +53,10 @@ type {{.Name|title}} {{.Name|title}} {{type $ .Type}} `json:"{{.Name}}"` {{- end}} } -{{- else if is "Verb" . -}} -{{.Comments|comment }} -{{if .Comments}}// +{{- else if is "Verb" .}} +{{if .Comments -}} +{{.Comments|comment}} +// {{end -}} //ftl:verb {{- if and (eq (type $ .Request) "ftl.Unit") (eq (type $ .Response) "ftl.Unit")}}