Output doc comments for package, structs, and fields.

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 <tag-name>:{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)),

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)
 

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" }
   ]
 }

gen/gen.go

@@ -10,6 +10,7 @@ import (
 	"maps"
 	"strings"
 	"text/template"
+	"unicode/utf8"
 
 	"github.com/ettle/strcase"
 	"github.com/hamba/avro/v2"
@@ -147,10 +148,28 @@ 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 = 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
 	pkg         string
+	pkgdoc      string
 	tags        map[string]TagStyle
 	fullName    bool
 	encoders    bool
@@ -257,7 +276,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 +338,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:           ensureTrailingPeriod(doc),
 		Tags:          g.tags,
 	}
 }
@@ -364,12 +383,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 +399,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:    ensureTrailingPeriod(doc),
 		Fields: fields,
 		Schema: schema,
 	}
@@ -393,7 +416,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
 }

gen/output_template.tmpl

@@ -1,3 +1,6 @@
+{{- if len .PackageDoc }}
+// {{ .PackageDoc }}
+{{- end }}
 package {{ .PackageName }}
 
 // Code generated by avro/gen. DO NOT EDIT.
@@ -12,10 +15,17 @@ package {{ .PackageName }}
 {{ end }}
 
 {{- range .Typedefs }}
+	{{- if len .Doc }}
+	// {{ .Doc }}
+	{{- else }}
 	// {{ .Name }} is a generated struct.
+	{{- end }}	
 	type {{ .Name }} struct {
 	{{- range .Fields }}
 		{{- $f := . }}
+		{{- if len $f.Doc }}
+		// {{ $f.Doc }}
+		{{- end }}
 		{{ .Name }} {{ .Type }} `avro:"{{ $f.AvroFieldName }}"
 		{{- range $tag, $style := .Tags }}
 			{{- " "}}{{ $tag }}:"

gen/testdata/golden.avsc

@@ -1,14 +1,17 @@
 {
   "type": "record",
   "name": "test",
+  "doc": "Test represents a golden record",
   "namespace": "a.b",
   "fields": [
     {
       "name": "aString",
+      "doc": "aString is just a string",
       "type": "string"
     },
     {
       "name": "aBoolean",
+      "doc": "aBoolean is just a boolean.",
       "type": "boolean"
     },
     {