From 8c534ab0d501b8963a62262727fa7fe4d91829d6 Mon Sep 17 00:00:00 2001 From: Blorgbeard Date: Sun, 19 May 2024 14:42:42 -0700 Subject: [PATCH 1/4] Output doc comments for package, structs, and fields. --- cmd/avrogen/main.go | 3 +++ cmd/avrogen/main_test.go | 4 ++-- cmd/avrogen/testdata/golden.go | 6 ++++-- cmd/avrogen/testdata/golden_encoders.go | 5 +++-- cmd/avrogen/testdata/golden_fullname.go | 5 +++-- cmd/avrogen/testdata/golden_stricttypes.go | 5 +++-- cmd/avrogen/testdata/schema.avsc | 3 ++- gen/gen.go | 22 +++++++++++++++++----- gen/output_template.tmpl | 12 ++++++++++-- gen/testdata/golden.avsc | 2 ++ gen/testdata/golden.go | 13 +++---------- gen/testdata/golden_encoders.go | 13 +++---------- gen/testdata/golden_fullname.go | 13 +++---------- gen/testdata/golden_multiple.go | 4 +--- 14 files changed, 59 insertions(+), 51 deletions(-) diff --git a/cmd/avrogen/main.go b/cmd/avrogen/main.go index e2a70d53..a2adfb4d 100644 --- a/cmd/avrogen/main.go +++ b/cmd/avrogen/main.go @@ -19,6 +19,7 @@ type config struct { TemplateFileName string Pkg string + PkgDoc string Out string Tags string FullName bool @@ -36,6 +37,7 @@ func realMain(args []string, stdout, stderr io.Writer) int { flgs := flag.NewFlagSet("avrogen", flag.ExitOnError) flgs.SetOutput(stderr) flgs.StringVar(&cfg.Pkg, "pkg", "", "The package name of the output file.") + flgs.StringVar(&cfg.PkgDoc, "pkgdoc", "", "The package doc comment to output.") flgs.StringVar(&cfg.Out, "o", "", "The output file path to write to instead of stdout.") flgs.StringVar(&cfg.Tags, "tags", "", "The additional field tags :{snake|camel|upper-camel|kebab}>[,...]") flgs.BoolVar(&cfg.FullName, "fullname", false, "Use the full name of the Record schema to create the struct name.") @@ -77,6 +79,7 @@ func realMain(args []string, stdout, stderr io.Writer) int { opts := []gen.OptsFunc{ gen.WithFullName(cfg.FullName), + gen.WithPackageDoc(cfg.PkgDoc), gen.WithEncoders(cfg.Encoders), gen.WithInitialisms(initialisms), gen.WithTemplate(string(template)), diff --git a/cmd/avrogen/main_test.go b/cmd/avrogen/main_test.go index 31f089fb..4788be0d 100644 --- a/cmd/avrogen/main_test.go +++ b/cmd/avrogen/main_test.go @@ -65,7 +65,7 @@ func TestAvroGen_RequiredFlags(t *testing.T) { func TestAvroGen_GeneratesSchemaStdout(t *testing.T) { var buf bytes.Buffer - args := []string{"avrogen", "-pkg", "testpkg", "testdata/schema.avsc"} + args := []string{"avrogen", "-pkg", "testpkg", "-pkgdoc", "package testpkg is generated from schema.avsc", "testdata/schema.avsc"} gotCode := realMain(args, &buf, io.Discard) require.Equal(t, 0, gotCode) @@ -80,7 +80,7 @@ func TestAvroGen_GeneratesSchema(t *testing.T) { t.Cleanup(func() { _ = os.RemoveAll(path) }) file := filepath.Join(path, "test.go") - args := []string{"avrogen", "-pkg", "testpkg", "-o", file, "testdata/schema.avsc"} + args := []string{"avrogen", "-o", file, "-pkg", "testpkg", "-pkgdoc", "package testpkg is generated from schema.avsc", "testdata/schema.avsc"} gotCode := realMain(args, io.Discard, io.Discard) require.Equal(t, 0, gotCode) diff --git a/cmd/avrogen/testdata/golden.go b/cmd/avrogen/testdata/golden.go index cf6eda1a..e76aef65 100644 --- a/cmd/avrogen/testdata/golden.go +++ b/cmd/avrogen/testdata/golden.go @@ -1,9 +1,11 @@ +// package testpkg is generated from schema.avsc package testpkg -// Code generated by avro/gen. DO NOT EDIT. +// Code generated by avro/gen. DO NOT EDIT MANUALLY. -// Test is a generated struct. +// Test is a test struct type Test struct { + // SomeString is a string SomeString string `avro:"someString"` SomeInt int `avro:"someInt"` } diff --git a/cmd/avrogen/testdata/golden_encoders.go b/cmd/avrogen/testdata/golden_encoders.go index 2cd13084..1c5b2fdb 100644 --- a/cmd/avrogen/testdata/golden_encoders.go +++ b/cmd/avrogen/testdata/golden_encoders.go @@ -1,13 +1,14 @@ package testpkg -// Code generated by avro/gen. DO NOT EDIT. +// Code generated by avro/gen. DO NOT EDIT MANUALLY. import ( "github.com/hamba/avro/v2" ) -// Test is a generated struct. +// Test is a test struct type Test struct { + // SomeString is a string SomeString string `avro:"someString"` SomeInt int `avro:"someInt"` } diff --git a/cmd/avrogen/testdata/golden_fullname.go b/cmd/avrogen/testdata/golden_fullname.go index 43b51d39..bdec65cd 100644 --- a/cmd/avrogen/testdata/golden_fullname.go +++ b/cmd/avrogen/testdata/golden_fullname.go @@ -1,9 +1,10 @@ package testpkg -// Code generated by avro/gen. DO NOT EDIT. +// Code generated by avro/gen. DO NOT EDIT MANUALLY. -// ABTest is a generated struct. +// Test is a test struct type ABTest struct { + // SomeString is a string SomeString string `avro:"someString"` SomeInt int `avro:"someInt"` } diff --git a/cmd/avrogen/testdata/golden_stricttypes.go b/cmd/avrogen/testdata/golden_stricttypes.go index 49f3dcbc..1e721b3e 100644 --- a/cmd/avrogen/testdata/golden_stricttypes.go +++ b/cmd/avrogen/testdata/golden_stricttypes.go @@ -1,9 +1,10 @@ package testpkg -// Code generated by avro/gen. DO NOT EDIT. +// Code generated by avro/gen. DO NOT EDIT MANUALLY. -// Test is a generated struct. +// Test is a test struct type Test struct { + // SomeString is a string SomeString string `avro:"someString"` SomeInt int32 `avro:"someInt"` } diff --git a/cmd/avrogen/testdata/schema.avsc b/cmd/avrogen/testdata/schema.avsc index 8196629b..8754f395 100644 --- a/cmd/avrogen/testdata/schema.avsc +++ b/cmd/avrogen/testdata/schema.avsc @@ -2,8 +2,9 @@ "type": "record", "name": "test", "namespace": "a.b", + "doc": "Test is a test struct", "fields": [ - { "name": "someString", "type": "string" }, + { "name": "someString", "type": "string", "doc": "SomeString is a string" }, { "name": "someInt", "type": "int" } ] } \ No newline at end of file diff --git a/gen/gen.go b/gen/gen.go index 720d6201..9a785522 100644 --- a/gen/gen.go +++ b/gen/gen.go @@ -147,10 +147,18 @@ func WithStrictTypes(b bool) OptsFunc { } } +// WithPackageDoc configures the generator to use output the given text as a package doc comment. +func WithPackageDoc(text string) OptsFunc { + return func(g *Generator) { + g.pkgdoc = text + } +} + // Generator generates Go structs from schemas. type Generator struct { template string pkg string + pkgdoc string tags map[string]TagStyle fullName bool encoders bool @@ -257,7 +265,7 @@ func (g *Generator) resolveRecordSchema(schema *avro.RecordSchema) string { typeName := g.resolveTypeName(schema) if !g.hasTypeDef(typeName) { - g.typedefs = append(g.typedefs, newType(typeName, fields, schema.String())) + g.typedefs = append(g.typedefs, newType(typeName, schema.Doc(), fields, schema.String())) } return typeName } @@ -319,12 +327,12 @@ func (g *Generator) resolveLogicalSchema(logicalType avro.LogicalType) string { return typ } -func (g *Generator) newField(name, typ, avroFieldDoc, avroFieldName string) field { +func (g *Generator) newField(name, typ, doc, avroFieldName string) field { return field{ Name: name, Type: typ, AvroFieldName: avroFieldName, - AvroFieldDoc: avroFieldDoc, + Doc: doc, Tags: g.tags, } } @@ -364,12 +372,14 @@ func (g *Generator) Write(w io.Writer) error { data := struct { WithEncoders bool PackageName string + PackageDoc string Imports []string ThirdPartyImports []string Typedefs []typedef }{ WithEncoders: g.encoders, PackageName: g.pkg, + PackageDoc: g.pkgdoc, Imports: append(g.imports, g.thirdPartyImports...), Typedefs: g.typedefs, } @@ -378,13 +388,15 @@ func (g *Generator) Write(w io.Writer) error { type typedef struct { Name string + Doc string Fields []field Schema string } -func newType(name string, fields []field, schema string) typedef { +func newType(name string, doc string, fields []field, schema string) typedef { return typedef{ Name: name, + Doc: doc, Fields: fields, Schema: schema, } @@ -393,7 +405,7 @@ func newType(name string, fields []field, schema string) typedef { type field struct { Name string Type string + Doc string AvroFieldName string - AvroFieldDoc string Tags map[string]TagStyle } diff --git a/gen/output_template.tmpl b/gen/output_template.tmpl index 94cbcf67..17a54119 100644 --- a/gen/output_template.tmpl +++ b/gen/output_template.tmpl @@ -1,6 +1,9 @@ +{{- if len .PackageDoc }} +// {{ .PackageDoc }} +{{- end }} package {{ .PackageName }} -// Code generated by avro/gen. DO NOT EDIT. +// Code generated by avro/gen. DO NOT EDIT MANUALLY. {{- $encoders := .WithEncoders }} {{ if len .Imports }} @@ -12,10 +15,15 @@ package {{ .PackageName }} {{ end }} {{- range .Typedefs }} - // {{ .Name }} is a generated struct. + {{- if len .Doc }} + // {{ .Doc }} + {{- end}} type {{ .Name }} struct { {{- range .Fields }} {{- $f := . }} + {{- if len $f.Doc }} + // {{ $f.Doc }} + {{- end }} {{ .Name }} {{ .Type }} `avro:"{{ $f.AvroFieldName }}" {{- range $tag, $style := .Tags }} {{- " "}}{{ $tag }}:" diff --git a/gen/testdata/golden.avsc b/gen/testdata/golden.avsc index 5c2300e8..ea7e76d4 100644 --- a/gen/testdata/golden.avsc +++ b/gen/testdata/golden.avsc @@ -1,10 +1,12 @@ { "type": "record", "name": "test", + "doc": "Test represents a golden record", "namespace": "a.b", "fields": [ { "name": "aString", + "doc": "aString is just a string", "type": "string" }, { diff --git a/gen/testdata/golden.go b/gen/testdata/golden.go index 66297736..724b5d3b 100644 --- a/gen/testdata/golden.go +++ b/gen/testdata/golden.go @@ -1,6 +1,6 @@ package something -// Code generated by avro/gen. DO NOT EDIT. +// Code generated by avro/gen. DO NOT EDIT MANUALLY. import ( "math/big" @@ -9,49 +9,42 @@ import ( "github.com/hamba/avro/v2" ) -// InnerRecord is a generated struct. type InnerRecord struct { InnerJustBytes []byte `avro:"innerJustBytes"` InnerPrimitiveNullableArrayUnion *[]string `avro:"innerPrimitiveNullableArrayUnion"` } -// RecordInMap is a generated struct. type RecordInMap struct { Name string `avro:"name"` } -// RecordInArray is a generated struct. type RecordInArray struct { AString string `avro:"aString"` } -// RecordInNullableUnion is a generated struct. type RecordInNullableUnion struct { AString string `avro:"aString"` } -// Record1InNonNullableUnion is a generated struct. type Record1InNonNullableUnion struct { AString string `avro:"aString"` } -// Record2InNonNullableUnion is a generated struct. type Record2InNonNullableUnion struct { AString string `avro:"aString"` } -// Record1InNullableUnion is a generated struct. type Record1InNullableUnion struct { AString string `avro:"aString"` } -// Record2InNullableUnion is a generated struct. type Record2InNullableUnion struct { AString string `avro:"aString"` } -// Test is a generated struct. +// Test represents a golden record type Test struct { + // aString is just a string AString string `avro:"aString"` ABoolean bool `avro:"aBoolean"` AnInt int `avro:"anInt"` diff --git a/gen/testdata/golden_encoders.go b/gen/testdata/golden_encoders.go index d3c0fbbb..5c8a8306 100644 --- a/gen/testdata/golden_encoders.go +++ b/gen/testdata/golden_encoders.go @@ -1,6 +1,6 @@ package something -// Code generated by avro/gen. DO NOT EDIT. +// Code generated by avro/gen. DO NOT EDIT MANUALLY. import ( "math/big" @@ -9,7 +9,6 @@ import ( "github.com/hamba/avro/v2" ) -// InnerRecord is a generated struct. type InnerRecord struct { InnerJustBytes []byte `avro:"innerJustBytes"` InnerPrimitiveNullableArrayUnion *[]string `avro:"innerPrimitiveNullableArrayUnion"` @@ -32,7 +31,6 @@ func (o *InnerRecord) Marshal() ([]byte, error) { return avro.Marshal(o.Schema(), o) } -// RecordInMap is a generated struct. type RecordInMap struct { Name string `avro:"name"` } @@ -54,7 +52,6 @@ func (o *RecordInMap) Marshal() ([]byte, error) { return avro.Marshal(o.Schema(), o) } -// RecordInArray is a generated struct. type RecordInArray struct { AString string `avro:"aString"` } @@ -76,7 +73,6 @@ func (o *RecordInArray) Marshal() ([]byte, error) { return avro.Marshal(o.Schema(), o) } -// RecordInNullableUnion is a generated struct. type RecordInNullableUnion struct { AString string `avro:"aString"` } @@ -98,7 +94,6 @@ func (o *RecordInNullableUnion) Marshal() ([]byte, error) { return avro.Marshal(o.Schema(), o) } -// Record1InNonNullableUnion is a generated struct. type Record1InNonNullableUnion struct { AString string `avro:"aString"` } @@ -120,7 +115,6 @@ func (o *Record1InNonNullableUnion) Marshal() ([]byte, error) { return avro.Marshal(o.Schema(), o) } -// Record2InNonNullableUnion is a generated struct. type Record2InNonNullableUnion struct { AString string `avro:"aString"` } @@ -142,7 +136,6 @@ func (o *Record2InNonNullableUnion) Marshal() ([]byte, error) { return avro.Marshal(o.Schema(), o) } -// Record1InNullableUnion is a generated struct. type Record1InNullableUnion struct { AString string `avro:"aString"` } @@ -164,7 +157,6 @@ func (o *Record1InNullableUnion) Marshal() ([]byte, error) { return avro.Marshal(o.Schema(), o) } -// Record2InNullableUnion is a generated struct. type Record2InNullableUnion struct { AString string `avro:"aString"` } @@ -186,8 +178,9 @@ func (o *Record2InNullableUnion) Marshal() ([]byte, error) { return avro.Marshal(o.Schema(), o) } -// Test is a generated struct. +// Test represents a golden record type Test struct { + // aString is just a string AString string `avro:"aString"` ABoolean bool `avro:"aBoolean"` AnInt int `avro:"anInt"` diff --git a/gen/testdata/golden_fullname.go b/gen/testdata/golden_fullname.go index cf81a16a..ef207ae6 100644 --- a/gen/testdata/golden_fullname.go +++ b/gen/testdata/golden_fullname.go @@ -1,6 +1,6 @@ package something -// Code generated by avro/gen. DO NOT EDIT. +// Code generated by avro/gen. DO NOT EDIT MANUALLY. import ( "math/big" @@ -9,49 +9,42 @@ import ( "github.com/hamba/avro/v2" ) -// ACInnerRecord is a generated struct. type ACInnerRecord struct { InnerJustBytes []byte `avro:"innerJustBytes"` InnerPrimitiveNullableArrayUnion *[]string `avro:"innerPrimitiveNullableArrayUnion"` } -// ABRecordInMap is a generated struct. type ABRecordInMap struct { Name string `avro:"name"` } -// ABRecordInArray is a generated struct. type ABRecordInArray struct { AString string `avro:"aString"` } -// ABRecordInNullableUnion is a generated struct. type ABRecordInNullableUnion struct { AString string `avro:"aString"` } -// ABRecord1InNonNullableUnion is a generated struct. type ABRecord1InNonNullableUnion struct { AString string `avro:"aString"` } -// ABRecord2InNonNullableUnion is a generated struct. type ABRecord2InNonNullableUnion struct { AString string `avro:"aString"` } -// ABRecord1InNullableUnion is a generated struct. type ABRecord1InNullableUnion struct { AString string `avro:"aString"` } -// ABRecord2InNullableUnion is a generated struct. type ABRecord2InNullableUnion struct { AString string `avro:"aString"` } -// ABTest is a generated struct. +// Test represents a golden record type ABTest struct { + // aString is just a string AString string `avro:"aString"` ABoolean bool `avro:"aBoolean"` AnInt int `avro:"anInt"` diff --git a/gen/testdata/golden_multiple.go b/gen/testdata/golden_multiple.go index 34c3f082..dcbfd74c 100644 --- a/gen/testdata/golden_multiple.go +++ b/gen/testdata/golden_multiple.go @@ -1,14 +1,12 @@ package something -// Code generated by avro/gen. DO NOT EDIT. +// Code generated by avro/gen. DO NOT EDIT MANUALLY. -// TestUnionType is a generated struct. type TestUnionType struct { Field1 int64 `avro:"Field1"` Field2 int `avro:"Field2"` } -// TestMain is a generated struct. type TestMain struct { TestUnion *TestUnionType `avro:"TestUnion"` } From f6a1c3d68c50cc24c455d6240f31a9d2ae54cd37 Mon Sep 17 00:00:00 2001 From: Blorgbeard Date: Sun, 9 Jun 2024 19:18:14 -0700 Subject: [PATCH 2/4] Address comments --- cmd/avrogen/testdata/golden.go | 2 +- cmd/avrogen/testdata/golden_encoders.go | 2 +- cmd/avrogen/testdata/golden_fullname.go | 2 +- cmd/avrogen/testdata/golden_stricttypes.go | 2 +- gen/gen.go | 2 +- gen/output_template.tmpl | 6 ++++-- gen/testdata/golden.go | 10 +++++++++- gen/testdata/golden_encoders.go | 10 +++++++++- gen/testdata/golden_fullname.go | 10 +++++++++- gen/testdata/golden_multiple.go | 4 +++- 10 files changed, 39 insertions(+), 11 deletions(-) diff --git a/cmd/avrogen/testdata/golden.go b/cmd/avrogen/testdata/golden.go index e76aef65..ac853d82 100644 --- a/cmd/avrogen/testdata/golden.go +++ b/cmd/avrogen/testdata/golden.go @@ -1,7 +1,7 @@ // package testpkg is generated from schema.avsc package testpkg -// Code generated by avro/gen. DO NOT EDIT MANUALLY. +// Code generated by avro/gen. DO NOT EDIT. // Test is a test struct type Test struct { diff --git a/cmd/avrogen/testdata/golden_encoders.go b/cmd/avrogen/testdata/golden_encoders.go index 1c5b2fdb..3223d40c 100644 --- a/cmd/avrogen/testdata/golden_encoders.go +++ b/cmd/avrogen/testdata/golden_encoders.go @@ -1,6 +1,6 @@ package testpkg -// Code generated by avro/gen. DO NOT EDIT MANUALLY. +// Code generated by avro/gen. DO NOT EDIT. import ( "github.com/hamba/avro/v2" diff --git a/cmd/avrogen/testdata/golden_fullname.go b/cmd/avrogen/testdata/golden_fullname.go index bdec65cd..fde53af1 100644 --- a/cmd/avrogen/testdata/golden_fullname.go +++ b/cmd/avrogen/testdata/golden_fullname.go @@ -1,6 +1,6 @@ package testpkg -// Code generated by avro/gen. DO NOT EDIT MANUALLY. +// Code generated by avro/gen. DO NOT EDIT. // Test is a test struct type ABTest struct { diff --git a/cmd/avrogen/testdata/golden_stricttypes.go b/cmd/avrogen/testdata/golden_stricttypes.go index 1e721b3e..0ddc2c8e 100644 --- a/cmd/avrogen/testdata/golden_stricttypes.go +++ b/cmd/avrogen/testdata/golden_stricttypes.go @@ -1,6 +1,6 @@ package testpkg -// Code generated by avro/gen. DO NOT EDIT MANUALLY. +// Code generated by avro/gen. DO NOT EDIT. // Test is a test struct type Test struct { diff --git a/gen/gen.go b/gen/gen.go index 9a785522..38a798c6 100644 --- a/gen/gen.go +++ b/gen/gen.go @@ -147,7 +147,7 @@ func WithStrictTypes(b bool) OptsFunc { } } -// WithPackageDoc configures the generator to use output the given text as a package doc comment. +// WithPackageDoc configures the generator to output the given text as a package doc comment. func WithPackageDoc(text string) OptsFunc { return func(g *Generator) { g.pkgdoc = text diff --git a/gen/output_template.tmpl b/gen/output_template.tmpl index 17a54119..1143fe52 100644 --- a/gen/output_template.tmpl +++ b/gen/output_template.tmpl @@ -3,7 +3,7 @@ {{- end }} package {{ .PackageName }} -// Code generated by avro/gen. DO NOT EDIT MANUALLY. +// Code generated by avro/gen. DO NOT EDIT. {{- $encoders := .WithEncoders }} {{ if len .Imports }} @@ -17,7 +17,9 @@ package {{ .PackageName }} {{- range .Typedefs }} {{- if len .Doc }} // {{ .Doc }} - {{- end}} + {{- else }} + // {{ .Name }} is a generated struct. + {{- end }} type {{ .Name }} struct { {{- range .Fields }} {{- $f := . }} diff --git a/gen/testdata/golden.go b/gen/testdata/golden.go index 724b5d3b..8eb5918f 100644 --- a/gen/testdata/golden.go +++ b/gen/testdata/golden.go @@ -1,6 +1,6 @@ package something -// Code generated by avro/gen. DO NOT EDIT MANUALLY. +// Code generated by avro/gen. DO NOT EDIT. import ( "math/big" @@ -9,35 +9,43 @@ import ( "github.com/hamba/avro/v2" ) +// InnerRecord is a generated struct. type InnerRecord struct { InnerJustBytes []byte `avro:"innerJustBytes"` InnerPrimitiveNullableArrayUnion *[]string `avro:"innerPrimitiveNullableArrayUnion"` } +// RecordInMap is a generated struct. type RecordInMap struct { Name string `avro:"name"` } +// RecordInArray is a generated struct. type RecordInArray struct { AString string `avro:"aString"` } +// RecordInNullableUnion is a generated struct. type RecordInNullableUnion struct { AString string `avro:"aString"` } +// Record1InNonNullableUnion is a generated struct. type Record1InNonNullableUnion struct { AString string `avro:"aString"` } +// Record2InNonNullableUnion is a generated struct. type Record2InNonNullableUnion struct { AString string `avro:"aString"` } +// Record1InNullableUnion is a generated struct. type Record1InNullableUnion struct { AString string `avro:"aString"` } +// Record2InNullableUnion is a generated struct. type Record2InNullableUnion struct { AString string `avro:"aString"` } diff --git a/gen/testdata/golden_encoders.go b/gen/testdata/golden_encoders.go index 5c8a8306..190a293c 100644 --- a/gen/testdata/golden_encoders.go +++ b/gen/testdata/golden_encoders.go @@ -1,6 +1,6 @@ package something -// Code generated by avro/gen. DO NOT EDIT MANUALLY. +// Code generated by avro/gen. DO NOT EDIT. import ( "math/big" @@ -9,6 +9,7 @@ import ( "github.com/hamba/avro/v2" ) +// InnerRecord is a generated struct. type InnerRecord struct { InnerJustBytes []byte `avro:"innerJustBytes"` InnerPrimitiveNullableArrayUnion *[]string `avro:"innerPrimitiveNullableArrayUnion"` @@ -31,6 +32,7 @@ func (o *InnerRecord) Marshal() ([]byte, error) { return avro.Marshal(o.Schema(), o) } +// RecordInMap is a generated struct. type RecordInMap struct { Name string `avro:"name"` } @@ -52,6 +54,7 @@ func (o *RecordInMap) Marshal() ([]byte, error) { return avro.Marshal(o.Schema(), o) } +// RecordInArray is a generated struct. type RecordInArray struct { AString string `avro:"aString"` } @@ -73,6 +76,7 @@ func (o *RecordInArray) Marshal() ([]byte, error) { return avro.Marshal(o.Schema(), o) } +// RecordInNullableUnion is a generated struct. type RecordInNullableUnion struct { AString string `avro:"aString"` } @@ -94,6 +98,7 @@ func (o *RecordInNullableUnion) Marshal() ([]byte, error) { return avro.Marshal(o.Schema(), o) } +// Record1InNonNullableUnion is a generated struct. type Record1InNonNullableUnion struct { AString string `avro:"aString"` } @@ -115,6 +120,7 @@ func (o *Record1InNonNullableUnion) Marshal() ([]byte, error) { return avro.Marshal(o.Schema(), o) } +// Record2InNonNullableUnion is a generated struct. type Record2InNonNullableUnion struct { AString string `avro:"aString"` } @@ -136,6 +142,7 @@ func (o *Record2InNonNullableUnion) Marshal() ([]byte, error) { return avro.Marshal(o.Schema(), o) } +// Record1InNullableUnion is a generated struct. type Record1InNullableUnion struct { AString string `avro:"aString"` } @@ -157,6 +164,7 @@ func (o *Record1InNullableUnion) Marshal() ([]byte, error) { return avro.Marshal(o.Schema(), o) } +// Record2InNullableUnion is a generated struct. type Record2InNullableUnion struct { AString string `avro:"aString"` } diff --git a/gen/testdata/golden_fullname.go b/gen/testdata/golden_fullname.go index ef207ae6..5ebcb5f5 100644 --- a/gen/testdata/golden_fullname.go +++ b/gen/testdata/golden_fullname.go @@ -1,6 +1,6 @@ package something -// Code generated by avro/gen. DO NOT EDIT MANUALLY. +// Code generated by avro/gen. DO NOT EDIT. import ( "math/big" @@ -9,35 +9,43 @@ import ( "github.com/hamba/avro/v2" ) +// ACInnerRecord is a generated struct. type ACInnerRecord struct { InnerJustBytes []byte `avro:"innerJustBytes"` InnerPrimitiveNullableArrayUnion *[]string `avro:"innerPrimitiveNullableArrayUnion"` } +// ABRecordInMap is a generated struct. type ABRecordInMap struct { Name string `avro:"name"` } +// ABRecordInArray is a generated struct. type ABRecordInArray struct { AString string `avro:"aString"` } +// ABRecordInNullableUnion is a generated struct. type ABRecordInNullableUnion struct { AString string `avro:"aString"` } +// ABRecord1InNonNullableUnion is a generated struct. type ABRecord1InNonNullableUnion struct { AString string `avro:"aString"` } +// ABRecord2InNonNullableUnion is a generated struct. type ABRecord2InNonNullableUnion struct { AString string `avro:"aString"` } +// ABRecord1InNullableUnion is a generated struct. type ABRecord1InNullableUnion struct { AString string `avro:"aString"` } +// ABRecord2InNullableUnion is a generated struct. type ABRecord2InNullableUnion struct { AString string `avro:"aString"` } diff --git a/gen/testdata/golden_multiple.go b/gen/testdata/golden_multiple.go index dcbfd74c..34c3f082 100644 --- a/gen/testdata/golden_multiple.go +++ b/gen/testdata/golden_multiple.go @@ -1,12 +1,14 @@ package something -// Code generated by avro/gen. DO NOT EDIT MANUALLY. +// Code generated by avro/gen. DO NOT EDIT. +// TestUnionType is a generated struct. type TestUnionType struct { Field1 int64 `avro:"Field1"` Field2 int `avro:"Field2"` } +// TestMain is a generated struct. type TestMain struct { TestUnion *TestUnionType `avro:"TestUnion"` } From a67ab0e785f53e85beb8e19b6595675e9044251c Mon Sep 17 00:00:00 2001 From: Blorgbeard Date: Mon, 17 Jun 2024 14:54:06 -0700 Subject: [PATCH 3/4] Ensure doc comments end with trailing period --- cmd/avrogen/testdata/golden.go | 6 +++--- cmd/avrogen/testdata/golden_encoders.go | 4 ++-- cmd/avrogen/testdata/golden_fullname.go | 4 ++-- cmd/avrogen/testdata/golden_stricttypes.go | 4 ++-- gen/gen.go | 17 ++++++++++++++--- gen/testdata/golden.avsc | 1 + gen/testdata/golden.go | 7 ++++--- gen/testdata/golden_encoders.go | 7 ++++--- gen/testdata/golden_fullname.go | 7 ++++--- 9 files changed, 36 insertions(+), 21 deletions(-) diff --git a/cmd/avrogen/testdata/golden.go b/cmd/avrogen/testdata/golden.go index ac853d82..d6f5ca85 100644 --- a/cmd/avrogen/testdata/golden.go +++ b/cmd/avrogen/testdata/golden.go @@ -1,11 +1,11 @@ -// package testpkg is generated from schema.avsc +// package testpkg is generated from schema.avsc. package testpkg // Code generated by avro/gen. DO NOT EDIT. -// Test is a test struct +// Test is a test struct. type Test struct { - // SomeString is a string + // SomeString is a string. SomeString string `avro:"someString"` SomeInt int `avro:"someInt"` } diff --git a/cmd/avrogen/testdata/golden_encoders.go b/cmd/avrogen/testdata/golden_encoders.go index 3223d40c..5f45e059 100644 --- a/cmd/avrogen/testdata/golden_encoders.go +++ b/cmd/avrogen/testdata/golden_encoders.go @@ -6,9 +6,9 @@ import ( "github.com/hamba/avro/v2" ) -// Test is a test struct +// Test is a test struct. type Test struct { - // SomeString is a string + // SomeString is a string. SomeString string `avro:"someString"` SomeInt int `avro:"someInt"` } diff --git a/cmd/avrogen/testdata/golden_fullname.go b/cmd/avrogen/testdata/golden_fullname.go index fde53af1..fff85177 100644 --- a/cmd/avrogen/testdata/golden_fullname.go +++ b/cmd/avrogen/testdata/golden_fullname.go @@ -2,9 +2,9 @@ package testpkg // Code generated by avro/gen. DO NOT EDIT. -// Test is a test struct +// Test is a test struct. type ABTest struct { - // SomeString is a string + // SomeString is a string. SomeString string `avro:"someString"` SomeInt int `avro:"someInt"` } diff --git a/cmd/avrogen/testdata/golden_stricttypes.go b/cmd/avrogen/testdata/golden_stricttypes.go index 0ddc2c8e..9b2a0ae5 100644 --- a/cmd/avrogen/testdata/golden_stricttypes.go +++ b/cmd/avrogen/testdata/golden_stricttypes.go @@ -2,9 +2,9 @@ package testpkg // Code generated by avro/gen. DO NOT EDIT. -// Test is a test struct +// Test is a test struct. type Test struct { - // SomeString is a string + // SomeString is a string. SomeString string `avro:"someString"` SomeInt int32 `avro:"someInt"` } diff --git a/gen/gen.go b/gen/gen.go index 38a798c6..eb06a764 100644 --- a/gen/gen.go +++ b/gen/gen.go @@ -10,6 +10,7 @@ import ( "maps" "strings" "text/template" + "unicode/utf8" "github.com/ettle/strcase" "github.com/hamba/avro/v2" @@ -150,10 +151,20 @@ func WithStrictTypes(b bool) OptsFunc { // WithPackageDoc configures the generator to output the given text as a package doc comment. func WithPackageDoc(text string) OptsFunc { return func(g *Generator) { - g.pkgdoc = text + g.pkgdoc = ensureTrailingPeriod(text) } } +func ensureTrailingPeriod(text string) string { + if text == "" { + return text + } + if last, _ := utf8.DecodeLastRuneInString(text); last == '.' { + return text + } + return text + "." +} + // Generator generates Go structs from schemas. type Generator struct { template string @@ -332,7 +343,7 @@ func (g *Generator) newField(name, typ, doc, avroFieldName string) field { Name: name, Type: typ, AvroFieldName: avroFieldName, - Doc: doc, + Doc: ensureTrailingPeriod(doc), Tags: g.tags, } } @@ -396,7 +407,7 @@ type typedef struct { func newType(name string, doc string, fields []field, schema string) typedef { return typedef{ Name: name, - Doc: doc, + Doc: ensureTrailingPeriod(doc), Fields: fields, Schema: schema, } diff --git a/gen/testdata/golden.avsc b/gen/testdata/golden.avsc index ea7e76d4..438d8426 100644 --- a/gen/testdata/golden.avsc +++ b/gen/testdata/golden.avsc @@ -11,6 +11,7 @@ }, { "name": "aBoolean", + "doc": "aBoolean is just a boolean.", "type": "boolean" }, { diff --git a/gen/testdata/golden.go b/gen/testdata/golden.go index 8eb5918f..f0cbfbde 100644 --- a/gen/testdata/golden.go +++ b/gen/testdata/golden.go @@ -50,10 +50,11 @@ type Record2InNullableUnion struct { AString string `avro:"aString"` } -// Test represents a golden record +// Test represents a golden record. type Test struct { - // aString is just a string - AString string `avro:"aString"` + // aString is just a string. + AString string `avro:"aString"` + // aBoolean is just a boolean. ABoolean bool `avro:"aBoolean"` AnInt int `avro:"anInt"` AFloat float32 `avro:"aFloat"` diff --git a/gen/testdata/golden_encoders.go b/gen/testdata/golden_encoders.go index 190a293c..73d35186 100644 --- a/gen/testdata/golden_encoders.go +++ b/gen/testdata/golden_encoders.go @@ -186,10 +186,11 @@ func (o *Record2InNullableUnion) Marshal() ([]byte, error) { return avro.Marshal(o.Schema(), o) } -// Test represents a golden record +// Test represents a golden record. type Test struct { - // aString is just a string - AString string `avro:"aString"` + // aString is just a string. + AString string `avro:"aString"` + // aBoolean is just a boolean. ABoolean bool `avro:"aBoolean"` AnInt int `avro:"anInt"` AFloat float32 `avro:"aFloat"` diff --git a/gen/testdata/golden_fullname.go b/gen/testdata/golden_fullname.go index 5ebcb5f5..4f398134 100644 --- a/gen/testdata/golden_fullname.go +++ b/gen/testdata/golden_fullname.go @@ -50,10 +50,11 @@ type ABRecord2InNullableUnion struct { AString string `avro:"aString"` } -// Test represents a golden record +// Test represents a golden record. type ABTest struct { - // aString is just a string - AString string `avro:"aString"` + // aString is just a string. + AString string `avro:"aString"` + // aBoolean is just a boolean. ABoolean bool `avro:"aBoolean"` AnInt int `avro:"anInt"` AFloat float32 `avro:"aFloat"` From 26fbf4b4c1183cf04f9cf506a5947a1f6be71a84 Mon Sep 17 00:00:00 2001 From: Nicholas Wiersma Date: Tue, 18 Jun 2024 06:30:35 +0200 Subject: [PATCH 4/4] Apply suggestions from code review fix: linter issue --- gen/gen.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gen/gen.go b/gen/gen.go index eb06a764..250bd7ac 100644 --- a/gen/gen.go +++ b/gen/gen.go @@ -404,7 +404,7 @@ type typedef struct { Schema string } -func newType(name string, doc string, fields []field, schema string) typedef { +func newType(name, doc string, fields []field, schema string) typedef { return typedef{ Name: name, Doc: ensureTrailingPeriod(doc),