fix: ensure schema comments are parsed and generated #1489 (part 2) (#…

…1505)

backend/protos/xyz/block/ftl/v1/schema/schema.proto

@@ -27,8 +27,9 @@ message Bytes {
 
 message Config {
   optional Position pos = 1;
-  string name = 2;
-  Type type = 3;
+  repeated string comments = 2;
+  string name = 3;
+  Type type = 4;
 }
 
 message Data {
@@ -43,8 +44,8 @@ message Data {
 
 message Database {
   optional Position pos = 1;
-  string name = 2;
-  repeated string comments = 3;
+  repeated string comments = 2;
+  string name = 3;
   string type = 4;
 }
 
@@ -218,8 +219,9 @@ message Schema {
 
 message Secret {
   optional Position pos = 1;
-  string name = 2;
-  Type type = 3;
+  repeated string comments = 2;
+  string name = 3;
+  Type type = 4;
 }
 
 message String {

backend/schema/config.go

@@ -2,6 +2,7 @@ package schema
 
 import (
 	"fmt"
+	"strings"
 
 	"google.golang.org/protobuf/reflect/protoreflect"
 
@@ -11,8 +12,9 @@ import (
 type Config struct {
 	Pos Position `parser:"" protobuf:"1,optional"`
 
-	Name string `parser:"'config' @Ident" protobuf:"2"`
-	Type Type   `parser:"@@" protobuf:"3"`
+	Comments []string `parser:"@Comment*" protobuf:"2"`
+	Name     string   `parser:"'config' @Ident" protobuf:"3"`
+	Type     Type     `parser:"@@" protobuf:"4"`
 }
 
 var _ Decl = (*Config)(nil)
@@ -21,13 +23,21 @@ var _ Symbol = (*Config)(nil)
 func (s *Config) GetName() string    { return s.Name }
 func (s *Config) IsExported() bool   { return false }
 func (s *Config) Position() Position { return s.Pos }
-func (s *Config) String() string     { return fmt.Sprintf("config %s %s", s.Name, s.Type) }
+func (s *Config) String() string {
+	w := &strings.Builder{}
+
+	fmt.Fprint(w, EncodeComments(s.Comments))
+	fmt.Fprintf(w, "config %s %s", s.Name, s.Type)
+
+	return w.String()
+}
 
 func (s *Config) ToProto() protoreflect.ProtoMessage {
 	return &schemapb.Config{
-		Pos:  posToProto(s.Pos),
-		Name: s.Name,
-		Type: typeToProto(s.Type),
+		Pos:      posToProto(s.Pos),
+		Comments: s.Comments,
+		Name:     s.Name,
+		Type:     typeToProto(s.Type),
 	}
 }
 
@@ -37,8 +47,9 @@ func (s *Config) schemaSymbol()          {}
 
 func ConfigFromProto(p *schemapb.Config) *Config {
 	return &Config{
-		Pos:  posFromProto(p.Pos),
-		Name: p.Name,
-		Type: typeToSchema(p.Type),
+		Pos:      posFromProto(p.Pos),
+		Comments: p.Comments,
+		Name:     p.Name,
+		Type:     typeToSchema(p.Type),
 	}
 }

backend/schema/data.go

@@ -155,7 +155,7 @@ func (d *Data) IsExported() bool { return d.Export }
 
 func (d *Data) String() string {
 	w := &strings.Builder{}
-	fmt.Fprint(w, encodeComments(d.Comments))
+	fmt.Fprint(w, EncodeComments(d.Comments))
 	typeParameters := ""
 	if len(d.TypeParameters) > 0 {
 		typeParameters = "<"

backend/schema/database.go

@@ -14,9 +14,9 @@ const PostgresDatabaseType = "postgres"
 type Database struct {
 	Pos Position `parser:"" protobuf:"1,optional"`
 
-	Comments []string `parser:"@Comment*" protobuf:"3"`
+	Comments []string `parser:"@Comment*" protobuf:"2"`
 	Type     string   `parser:"'database' @'postgres'" protobuf:"4"`
-	Name     string   `parser:"@Ident" protobuf:"2"`
+	Name     string   `parser:"@Ident" protobuf:"3"`
 }
 
 var _ Decl = (*Database)(nil)
@@ -28,17 +28,17 @@ func (*Database) schemaSymbol()            {}
 func (d *Database) schemaChildren() []Node { return nil }
 func (d *Database) String() string {
 	w := &strings.Builder{}
-	fmt.Fprint(w, encodeComments(d.Comments))
+	fmt.Fprint(w, EncodeComments(d.Comments))
 	fmt.Fprintf(w, "database %s %s", d.Type, d.Name)
 	return w.String()
 }
 
 func (d *Database) ToProto() proto.Message {
 	return &schemapb.Database{
 		Pos:      posToProto(d.Pos),
+		Comments: d.Comments,
 		Name:     d.Name,
 		Type:     d.Type,
-		Comments: d.Comments,
 	}
 }
 
@@ -48,8 +48,8 @@ func (d *Database) IsExported() bool { return false }
 func DatabaseFromProto(s *schemapb.Database) *Database {
 	return &Database{
 		Pos:      posFromProto(s.Pos),
-		Name:     s.Name,
 		Comments: s.Comments,
+		Name:     s.Name,
 		Type:     s.Type,
 	}
 }

backend/schema/encoding.go

@@ -27,13 +27,20 @@ func encodeMetadata(metadata []Metadata) string {
 	return strings.TrimSuffix(w.String(), "\n")
 }
 
-func encodeComments(comments []string) string {
+func EncodeComments(comments []string) string {
 	if len(comments) == 0 {
 		return ""
 	}
+
 	w := &strings.Builder{}
 	for _, c := range comments {
-		fmt.Fprintf(w, "// %s\n", c)
+		space := ""
+		// Empty lines should not have a trailing space.
+		if c != "" {
+			space = " "
+		}
+
+		fmt.Fprintf(w, "//%s%s\n", space, c)
 	}
 	return w.String()
 }

backend/schema/enum.go

@@ -26,7 +26,7 @@ func (e *Enum) Position() Position { return e.Pos }
 
 func (e *Enum) String() string {
 	w := &strings.Builder{}
-	fmt.Fprint(w, encodeComments(e.Comments))
+	fmt.Fprint(w, EncodeComments(e.Comments))
 	if e.Export {
 		fmt.Fprint(w, "export ")
 	}
@@ -113,7 +113,7 @@ func (e *EnumVariant) schemaChildren() []Node { return []Node{e.Value} }
 
 func (e *EnumVariant) String() string {
 	w := &strings.Builder{}
-	fmt.Fprint(w, encodeComments(e.Comments))
+	fmt.Fprint(w, EncodeComments(e.Comments))
 	fmt.Fprintf(w, e.Name)
 	if e.Value != nil {
 		if _, ok := e.Value.(*TypeValue); ok {

backend/schema/field.go

@@ -32,7 +32,7 @@ func (f *Field) schemaChildren() []Node {
 }
 func (f *Field) String() string {
 	w := &strings.Builder{}
-	fmt.Fprint(w, encodeComments(f.Comments))
+	fmt.Fprint(w, EncodeComments(f.Comments))
 	fmt.Fprintf(w, "%s %s", f.Name, f.Type.String())
 	for _, md := range f.Metadata {
 		fmt.Fprintf(w, " %s", md.String())

backend/schema/module.go

@@ -76,7 +76,7 @@ type spacingRule struct {
 
 func (m *Module) String() string {
 	w := &strings.Builder{}
-	fmt.Fprint(w, encodeComments(m.Comments))
+	fmt.Fprint(w, EncodeComments(m.Comments))
 	if m.Builtin {
 		fmt.Fprint(w, "builtin ")
 	}

backend/schema/schema_test.go

@@ -19,9 +19,12 @@ func TestSchemaString(t *testing.T) {
 	expected := Builtins().String() + `
 // A comment
 module todo {
+  // A config value
   config configValue String
+  // Shhh
   secret secretValue String
 
+  // A database
   database postgres testdb
 
   export data CreateRequest {
@@ -421,8 +424,11 @@ func TestParseModule(t *testing.T) {
 	input := `
 // A comment
 module todo {
+  // A config value
   config configValue String
+  // Shhh
   secret secretValue String
+  // A database
   database postgres testdb
 
   export data CreateRequest {
@@ -497,16 +503,19 @@ var testSchema = MustValidate(&Schema{
 			Comments: []string{"A comment"},
 			Decls: []Decl{
 				&Secret{
-					Name: "secretValue",
-					Type: &String{},
+					Comments: []string{"Shhh"},
+					Name:     "secretValue",
+					Type:     &String{},
 				},
 				&Config{
-					Name: "configValue",
-					Type: &String{},
+					Comments: []string{"A config value"},
+					Name:     "configValue",
+					Type:     &String{},
 				},
 				&Database{
-					Name: "testdb",
-					Type: "postgres",
+					Comments: []string{"A database"},
+					Name:     "testdb",
+					Type:     "postgres",
 				},
 				&Data{
 					Name:   "CreateRequest",

backend/schema/secret.go

@@ -2,6 +2,7 @@ package schema
 
 import (
 	"fmt"
+	"strings"
 
 	"google.golang.org/protobuf/reflect/protoreflect"
 
@@ -11,8 +12,9 @@ import (
 type Secret struct {
 	Pos Position `parser:"" protobuf:"1,optional"`
 
-	Name string `parser:"'secret' @Ident" protobuf:"2"`
-	Type Type   `parser:"@@" protobuf:"3"`
+	Comments []string `parser:"@Comment*" protobuf:"2"`
+	Name     string   `parser:"'secret' @Ident" protobuf:"3"`
+	Type     Type     `parser:"@@" protobuf:"4"`
 }
 
 var _ Decl = (*Secret)(nil)
@@ -21,25 +23,33 @@ var _ Symbol = (*Secret)(nil)
 func (s *Secret) GetName() string    { return s.Name }
 func (s *Secret) IsExported() bool   { return false }
 func (s *Secret) Position() Position { return s.Pos }
-func (s *Secret) String() string     { return fmt.Sprintf("secret %s %s", s.Name, s.Type) }
+func (s *Secret) String() string {
+	w := &strings.Builder{}
+
+	fmt.Fprint(w, EncodeComments(s.Comments))
+	fmt.Fprintf(w, "secret %s %s", s.Name, s.Type)
+
+	return w.String()
+}
 
 func (s *Secret) ToProto() protoreflect.ProtoMessage {
 	return &schemapb.Secret{
-		Pos:  posToProto(s.Pos),
-		Name: s.Name,
-		Type: typeToProto(s.Type),
+		Pos:      posToProto(s.Pos),
+		Name:     s.Name,
+		Comments: s.Comments,
+		Type:     typeToProto(s.Type),
 	}
 }
 
 func (s *Secret) schemaChildren() []Node { return []Node{s.Type} }
+func (s *Secret) schemaDecl()            {}
+func (s *Secret) schemaSymbol()          {}
 
-func (s *Secret) schemaDecl()   {}
-func (s *Secret) schemaSymbol() {}
-
-func SecretFromProto(p *schemapb.Secret) *Secret {
+func SecretFromProto(s *schemapb.Secret) *Secret {
 	return &Secret{
-		Pos:  posFromProto(p.Pos),
-		Name: p.Name,
-		Type: typeToSchema(p.Type),
+		Pos:      posFromProto(s.Pos),
+		Name:     s.Name,
+		Comments: s.Comments,
+		Type:     typeToSchema(s.Type),
 	}
 }

backend/schema/verb.go

@@ -75,7 +75,7 @@ func (v *Verb) IsExported() bool { return v.Export }
 
 func (v *Verb) String() string {
 	w := &strings.Builder{}
-	fmt.Fprint(w, encodeComments(v.Comments))
+	fmt.Fprint(w, EncodeComments(v.Comments))
 	if v.Export {
 		fmt.Fprint(w, "export ")
 	}

buildengine/build_go_test.go

@@ -128,6 +128,7 @@ type EchoRequest struct {
 }
 
 // This is an echo data response.
+//
 type EchoResponse struct {
 }
 
@@ -219,6 +220,7 @@ import (
 var _ = context.Background
 
 // Request data type.
+//
 type Req struct {
 }