From 9f5d36301b20af67713af325865fab514abbfc98 Mon Sep 17 00:00:00 2001
From: Bevan Arps <bevan.arps@microsoft.com>
Date: Wed, 24 Jun 2020 21:56:31 +1200
Subject: [PATCH] Improve comment formatting (#152)

* Move addDocComment() into separate helper function

* Reformat comments

* Add blank lines before comment blocks

* Use Regexp to translate <br/>

* Use Index() and LastIndex() to simplify choosing breakpoints in lines

* Clarify comment

Co-authored-by: Dave Fellows <dave.fellows@microsoft.com>

* Fix comment

* Change method to internal, but document it anyway

* Fix search/replace typo & clarify comments

* Update golden files with modified comments

* Move definition of brRegex next to formatDocComment()

* Add missing file headers

Co-authored-by: Dave Fellows <dave.fellows@microsoft.com>
Co-authored-by: George Pollard <gpollard@microsoft.com>
---
 hack/generator/pkg/astmodel/comments.go       | 100 ++++++++++++++++++
 hack/generator/pkg/astmodel/comments_test.go  |  77 ++++++++++++++
 .../pkg/astmodel/field_definition.go          |  16 +--
 .../generator/pkg/astmodel/file_definition.go |  51 +++++++--
 .../pkg/astmodel/simple_type_definer.go       |   9 +-
 .../pkg/astmodel/struct_definition.go         |   3 +-
 ...rates_field_if_other_fields_present.golden |   2 +-
 ...f_unset_and_no_other_fields_present.golden |   2 +-
 ...map_type_if_no_other_fields_present.golden |   2 +-
 ...Generates_nothing_if_set_to_'false'.golden |   2 +-
 ...g_if_unset_and_other_fields_present.golden |   2 +-
 ...lOf_collapses_duplicate_named_types.golden |   4 +-
 ...f_collapses_duplicate_unnamed_types.golden |   2 +-
 .../AllOf/AllOf_generates_wrapper_type.golden |  12 ++-
 ...eOf_collapses_duplicate_named_types.golden |   4 +-
 ...f_collapses_duplicate_unnamed_types.golden |   2 +-
 ...erates_wrapper_for_inner_properties.golden |  13 ++-
 ...es_wrapper_type_with_marshal_helper.golden |  19 ++--
 ...med_properties_from_anonymous_types.golden |  13 ++-
 ...enced_definitions_are_not_generated.golden |   2 +-
 .../Enums_have_required_validation.golden     |   3 +-
 .../Optional_properties_are_pointers.golden   |   2 +-
 ...nown_type_is_generated_as_interface.golden |   2 +-
 ...properties_have_appropriate_comment.golden |   3 +-
 24 files changed, 280 insertions(+), 67 deletions(-)
 create mode 100644 hack/generator/pkg/astmodel/comments.go
 create mode 100644 hack/generator/pkg/astmodel/comments_test.go

diff --git a/hack/generator/pkg/astmodel/comments.go b/hack/generator/pkg/astmodel/comments.go
new file mode 100644
index 00000000000..e6fb0e77e00
--- /dev/null
+++ b/hack/generator/pkg/astmodel/comments.go
@@ -0,0 +1,100 @@
+/*
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT license.
+ */
+
+package astmodel
+
+import (
+	"go/ast"
+	"regexp"
+	"strings"
+)
+
+// Utility methods for adding comments
+
+func addDocComment(commentList *[]*ast.Comment, comment string, width int) {
+	for _, c := range formatDocComment(comment, width) {
+		line := strings.TrimSpace(c)
+		if !strings.HasPrefix(line, "//") {
+			line = "//" + line
+		}
+
+		if *commentList == nil {
+			line = "\n" + line
+		}
+
+		*commentList = append(*commentList, &ast.Comment{
+			Text: line,
+		})
+	}
+}
+
+// formatDocComment splits the supplied comment string up ready for use as a documentation comment
+func formatDocComment(comment string, width int) []string {
+	// Remove markdown bolding
+	text := strings.ReplaceAll(comment, "**", "")
+
+	// Turn <br> and <br/> into \n
+	text = brRegex.ReplaceAllLiteralString(text, "\n")
+
+	// Split into individual lines
+	lines := strings.Split(text, "\n")
+
+	// Trim whitespace
+	for i, l := range lines {
+		lines[i] = strings.TrimSpace(l)
+	}
+
+	// Wordwrap and return
+	return docCommentWrap(lines, width)
+}
+
+var brRegex = regexp.MustCompile("<br[^/>]*/?>")
+
+func docCommentWrap(lines []string, width int) []string {
+	var result []string
+	for _, l := range lines {
+		result = append(result, wordWrap(l, width)...)
+	}
+
+	return result
+}
+
+func wordWrap(text string, width int) []string {
+	var result []string
+
+	start := 0
+	for start < len(text) {
+		finish := findBreakPoint(text, start, width)
+		result = append(result, text[start:finish+1])
+		start = finish + 1
+	}
+
+	return result
+}
+
+// findBreakPoint finds the character at which to break two lines
+// Returned index points to the last character that should be included on the line
+// If breaking at a space, this will give a trailing space, but allows for
+// breaking at other points too as no characters will be omitted.
+func findBreakPoint(line string, start int, width int) int {
+	limit := start + width + 1
+	if limit >= len(line) {
+		return len(line) - 1
+	}
+
+	// Look for a word break within the line
+	index := strings.LastIndex(line[start:limit], " ")
+	if index >= 0 {
+		return start + index
+	}
+
+	// Line contains continuous text, we don't want to break it in two, so find the end of it
+	index = strings.Index(line[limit:], " ")
+	if index >= 0 {
+		return limit + index
+	}
+
+	return len(line) - 1
+}
diff --git a/hack/generator/pkg/astmodel/comments_test.go b/hack/generator/pkg/astmodel/comments_test.go
new file mode 100644
index 00000000000..995e38063f2
--- /dev/null
+++ b/hack/generator/pkg/astmodel/comments_test.go
@@ -0,0 +1,77 @@
+/*
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT license.
+ */
+
+package astmodel
+
+import (
+	. "github.com/onsi/gomega"
+	"testing"
+)
+
+func TestDocumentationCommentFormatting(t *testing.T) {
+	cases := []struct {
+		comment string
+		results []string
+	}{
+		// Expect short single line comments to be unchanged
+		{"foo", []string{"foo"}},
+		{"bar", []string{"bar"}},
+		{"baz", []string{"baz"}},
+		// Leading and trailing whitespace is trimmed
+		{"    foo", []string{"foo"}},
+		{"foo    ", []string{"foo"}},
+		{"  foo  ", []string{"foo"}},
+		// Expect comments with embedded newlines to be split
+		{"foo\nbar", []string{"foo", "bar"}},
+		{"foo\nbar\nbaz", []string{"foo", "bar", "baz"}},
+		// Expect comments with html style <br> to be split
+		{"foo<br>bar", []string{"foo", "bar"}},
+		{"foo<br>bar<br>baz", []string{"foo", "bar", "baz"}},
+		{"foo<br/>bar", []string{"foo", "bar"}},
+		{"foo<br/>bar<br/>baz", []string{"foo", "bar", "baz"}},
+		// Expect markdown bold to be removed
+		{"**foo**\nbar", []string{"foo", "bar"}},
+		{"foo\n**bar**", []string{"foo", "bar"}},
+		{"foo\n**bar**\nbaz", []string{"foo", "bar", "baz"}},
+		// Expect long lines to be wrapped
+		{
+			"Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
+			[]string{
+				"Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do ",
+				"eiusmod tempor incididunt ut labore et dolore magna aliqua.",
+			}},
+	}
+
+	for _, c := range cases {
+		c := c
+		t.Run(c.comment, func(t *testing.T) {
+			g := NewGomegaWithT(t)
+			lines := formatDocComment(c.comment, 64)
+			g.Expect(lines).To(Equal(c.results))
+		})
+	}
+}
+
+func TestWordWrap(t *testing.T) {
+	cases := []struct {
+		text    string
+		width   int
+		results []string
+	}{
+		{"this is a simple line of text", 15, []string{"this is a ", "simple line of ", "text"}},
+		{"this is a simple line of text", 16, []string{"this is a simple ", "line of text"}},
+		{"this is a simple line of text", 20, []string{"this is a simple ", "line of text"}},
+		{"this is a simple line of text", 21, []string{"this is a simple line ", "of text"}},
+	}
+
+	for _, c := range cases {
+		c := c
+		t.Run(c.text, func(t *testing.T) {
+			g := NewGomegaWithT(t)
+			lines := wordWrap(c.text, c.width)
+			g.Expect(lines).To(Equal(c.results))
+		})
+	}
+}
diff --git a/hack/generator/pkg/astmodel/field_definition.go b/hack/generator/pkg/astmodel/field_definition.go
index 2238a23d07a..ccef1901419 100644
--- a/hack/generator/pkg/astmodel/field_definition.go
+++ b/hack/generator/pkg/astmodel/field_definition.go
@@ -107,27 +107,15 @@ func (field *FieldDefinition) AsField(codeGenerationContext *CodeGenerationConte
 		},
 	}
 
-	addDocComment := func(comment string) {
-		newLine := ""
-		if result.Doc.List == nil {
-			// if first comment, add a newline
-			newLine = "\n"
-		}
-
-		result.Doc.List = append(result.Doc.List, &ast.Comment{
-			Text: newLine + comment,
-		})
-	}
-
 	// generate validation comments:
 	for _, validation := range field.validations {
 		// these are not doc comments but they must go here to be emitted before the field
-		addDocComment(GenerateKubebuilderComment(validation))
+		addDocComment(&result.Doc.List, GenerateKubebuilderComment(validation), 200)
 	}
 
 	// generate doc comment:
 	if field.description != "" {
-		addDocComment(fmt.Sprintf("/*%s: %s*/", field.fieldName, field.description))
+		addDocComment(&result.Doc.List, fmt.Sprintf("%s: %s", field.fieldName, field.description), 80)
 	}
 
 	return result
diff --git a/hack/generator/pkg/astmodel/file_definition.go b/hack/generator/pkg/astmodel/file_definition.go
index b7f902f6b62..470c8b85d11 100644
--- a/hack/generator/pkg/astmodel/file_definition.go
+++ b/hack/generator/pkg/astmodel/file_definition.go
@@ -6,6 +6,7 @@
 package astmodel
 
 import (
+	"bufio"
 	"bytes"
 	"go/ast"
 	"go/format"
@@ -14,6 +15,7 @@ import (
 	"io"
 	"os"
 	"sort"
+	"strings"
 
 	"k8s.io/klog/v2"
 )
@@ -175,21 +177,24 @@ func (file FileDefinition) SaveToWriter(filename string, dst io.Writer) error {
 	fset := token.NewFileSet()
 	fset.AddFile(filename, 1, 102400)
 
-	var buffer bytes.Buffer
-	err := format.Node(&buffer, fset, original)
+	var unformattedBuffer bytes.Buffer
+	err := format.Node(&unformattedBuffer, fset, original)
 	if err != nil {
 		return err
 	}
 
-	// Parse it out of the buffer again so we can "go fmt" it
-	var toFormat ast.Node
-	toFormat, err = parser.ParseFile(fset, filename, &buffer, parser.ParseComments)
+	// This is a nasty technique with only one redeeming characteristic: It works
+	reformattedBuffer := file.addBlankLinesBeforeComments(unformattedBuffer)
+
+	// Read the source from the memory buffer (has the effect similar to 'go fmt')
+	var cleanAst ast.Node
+	cleanAst, err = parser.ParseFile(fset, filename, &reformattedBuffer, parser.ParseComments)
 	if err != nil {
 		klog.Errorf("Failed to reformat code (%s); keeping code as is.", err)
-		toFormat = original
+		cleanAst = original
 	}
 
-	return format.Node(dst, fset, toFormat)
+	return format.Node(dst, fset, cleanAst)
 }
 
 // SaveToFile writes this generated file to disk
@@ -204,3 +209,35 @@ func (file FileDefinition) SaveToFile(filePath string) error {
 
 	return file.SaveToWriter(filePath, f)
 }
+
+// addBlankLinesBeforeComments reads the source in the passed buffer and injects a blank line just
+// before each '//' style comment so that the comments are nicely spaced out in the generated code.
+func (file FileDefinition) addBlankLinesBeforeComments(buffer bytes.Buffer) bytes.Buffer {
+	// Read all the lines from the buffer
+	var lines []string
+	reader := bufio.NewReader(&buffer)
+	scanner := bufio.NewScanner(reader)
+	for scanner.Scan() {
+		lines = append(lines, scanner.Text())
+	}
+
+	isComment := func(s string) bool {
+		return strings.HasPrefix(strings.TrimSpace(s), "//")
+	}
+
+	var result bytes.Buffer
+	lastLineWasComment := false
+	for _, l := range lines {
+		// Add blank line prior to each comment block
+		if !lastLineWasComment && isComment(l) {
+			result.WriteString("\n")
+		}
+
+		result.WriteString(l)
+		result.WriteString("\n")
+
+		lastLineWasComment = isComment(l)
+	}
+
+	return result
+}
diff --git a/hack/generator/pkg/astmodel/simple_type_definer.go b/hack/generator/pkg/astmodel/simple_type_definer.go
index 86249e5b33b..107f6f82b1f 100644
--- a/hack/generator/pkg/astmodel/simple_type_definer.go
+++ b/hack/generator/pkg/astmodel/simple_type_definer.go
@@ -41,13 +41,8 @@ func (std *SimpleTypeDefiner) WithDescription(desc *string) TypeDefiner {
 func (std *SimpleTypeDefiner) AsDeclarations(codeGenerationContext *CodeGenerationContext) []ast.Decl {
 	var docComments *ast.CommentGroup
 	if std.description != nil {
-		docComments = &ast.CommentGroup{
-			List: []*ast.Comment{
-				{
-					Text: "\n/*" + *std.description + "*/",
-				},
-			},
-		}
+		docComments = &ast.CommentGroup{}
+		addDocComment(&docComments.List, *std.description, 120)
 	}
 
 	return []ast.Decl{
diff --git a/hack/generator/pkg/astmodel/struct_definition.go b/hack/generator/pkg/astmodel/struct_definition.go
index 543ad942eb6..918067d322c 100644
--- a/hack/generator/pkg/astmodel/struct_definition.go
+++ b/hack/generator/pkg/astmodel/struct_definition.go
@@ -81,8 +81,7 @@ func (definition *StructDefinition) AsDeclarations(codeGenerationContext *CodeGe
 	}
 
 	if definition.description != nil {
-		declaration.Doc.List = append(declaration.Doc.List,
-			&ast.Comment{Text: "\n/*" + *definition.description + "*/"})
+		addDocComment(&declaration.Doc.List, *definition.description, 200)
 	}
 
 	declarations := []ast.Decl{declaration}
diff --git a/hack/generator/pkg/jsonast/testdata/AdditionalProperties/Generates_field_if_other_fields_present.golden b/hack/generator/pkg/jsonast/testdata/AdditionalProperties/Generates_field_if_other_fields_present.golden
index 77eda979150..462bba612d5 100644
--- a/hack/generator/pkg/jsonast/testdata/AdditionalProperties/Generates_field_if_other_fields_present.golden
+++ b/hack/generator/pkg/jsonast/testdata/AdditionalProperties/Generates_field_if_other_fields_present.golden
@@ -5,7 +5,7 @@ package v20200101
 
 import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 
-/*Generated from: https://test.test/schemas/2020-01-01/test.json*/
+//Generated from: https://test.test/schemas/2020-01-01/test.json
 type Test struct {
 	Tags *TestTags `json:"tags"`
 }
diff --git a/hack/generator/pkg/jsonast/testdata/AdditionalProperties/Generates_map[string]interface{}_if_unset_and_no_other_fields_present.golden b/hack/generator/pkg/jsonast/testdata/AdditionalProperties/Generates_map[string]interface{}_if_unset_and_no_other_fields_present.golden
index 927f9c03c23..f7f416b6299 100644
--- a/hack/generator/pkg/jsonast/testdata/AdditionalProperties/Generates_map[string]interface{}_if_unset_and_no_other_fields_present.golden
+++ b/hack/generator/pkg/jsonast/testdata/AdditionalProperties/Generates_map[string]interface{}_if_unset_and_no_other_fields_present.golden
@@ -5,7 +5,7 @@ package v20200101
 
 import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 
-/*Generated from: https://test.test/schemas/2020-01-01/test.json*/
+//Generated from: https://test.test/schemas/2020-01-01/test.json
 type Test struct {
 	Tags *map[string]interface{} `json:"tags"`
 }
diff --git a/hack/generator/pkg/jsonast/testdata/AdditionalProperties/Generates_map_type_if_no_other_fields_present.golden b/hack/generator/pkg/jsonast/testdata/AdditionalProperties/Generates_map_type_if_no_other_fields_present.golden
index 1a6b7e34ae7..18c70ec4ec4 100644
--- a/hack/generator/pkg/jsonast/testdata/AdditionalProperties/Generates_map_type_if_no_other_fields_present.golden
+++ b/hack/generator/pkg/jsonast/testdata/AdditionalProperties/Generates_map_type_if_no_other_fields_present.golden
@@ -5,7 +5,7 @@ package v20200101
 
 import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 
-/*Generated from: https://test.test/schemas/2020-01-01/test.json*/
+//Generated from: https://test.test/schemas/2020-01-01/test.json
 type Test struct {
 	Tags *map[string]float64 `json:"tags"`
 }
diff --git a/hack/generator/pkg/jsonast/testdata/AdditionalProperties/Generates_nothing_if_set_to_'false'.golden b/hack/generator/pkg/jsonast/testdata/AdditionalProperties/Generates_nothing_if_set_to_'false'.golden
index 43b9c1f9e34..0de16296cd3 100644
--- a/hack/generator/pkg/jsonast/testdata/AdditionalProperties/Generates_nothing_if_set_to_'false'.golden
+++ b/hack/generator/pkg/jsonast/testdata/AdditionalProperties/Generates_nothing_if_set_to_'false'.golden
@@ -5,7 +5,7 @@ package v20200101
 
 import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 
-/*Generated from: https://test.test/schemas/2020-01-01/test.json*/
+//Generated from: https://test.test/schemas/2020-01-01/test.json
 type Test struct {
 	Tags *TestTags `json:"tags"`
 }
diff --git a/hack/generator/pkg/jsonast/testdata/AdditionalProperties/Generates_nothing_if_unset_and_other_fields_present.golden b/hack/generator/pkg/jsonast/testdata/AdditionalProperties/Generates_nothing_if_unset_and_other_fields_present.golden
index 7b54ca7385c..d52a07be109 100644
--- a/hack/generator/pkg/jsonast/testdata/AdditionalProperties/Generates_nothing_if_unset_and_other_fields_present.golden
+++ b/hack/generator/pkg/jsonast/testdata/AdditionalProperties/Generates_nothing_if_unset_and_other_fields_present.golden
@@ -5,7 +5,7 @@ package v20200101
 
 import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 
-/*Generated from: https://test.test/schemas/2020-01-01/test.json*/
+//Generated from: https://test.test/schemas/2020-01-01/test.json
 type Test struct {
 	Tags *TestTags `json:"tags"`
 }
diff --git a/hack/generator/pkg/jsonast/testdata/AllOf/AllOf_collapses_duplicate_named_types.golden b/hack/generator/pkg/jsonast/testdata/AllOf/AllOf_collapses_duplicate_named_types.golden
index 700bf6dbefe..1ba1c17b14c 100644
--- a/hack/generator/pkg/jsonast/testdata/AllOf/AllOf_collapses_duplicate_named_types.golden
+++ b/hack/generator/pkg/jsonast/testdata/AllOf/AllOf_collapses_duplicate_named_types.golden
@@ -5,10 +5,10 @@ package v20200101
 
 import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 
-/*Generated from: https://test.test/schemas/2020-01-01/test.json#/definitions/Foo*/
+//Generated from: https://test.test/schemas/2020-01-01/test.json#/definitions/Foo
 type Foo struct {
 	Name *string `json:"name"`
 }
 
-/*Generated from: https://test.test/schemas/2020-01-01/test.json*/
+//Generated from: https://test.test/schemas/2020-01-01/test.json
 type Test Foo
diff --git a/hack/generator/pkg/jsonast/testdata/AllOf/AllOf_collapses_duplicate_unnamed_types.golden b/hack/generator/pkg/jsonast/testdata/AllOf/AllOf_collapses_duplicate_unnamed_types.golden
index 329bfeebe9f..66316251853 100644
--- a/hack/generator/pkg/jsonast/testdata/AllOf/AllOf_collapses_duplicate_unnamed_types.golden
+++ b/hack/generator/pkg/jsonast/testdata/AllOf/AllOf_collapses_duplicate_unnamed_types.golden
@@ -5,7 +5,7 @@ package v20200101
 
 import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 
-/*Generated from: https://test.test/schemas/2020-01-01/test.json*/
+//Generated from: https://test.test/schemas/2020-01-01/test.json
 type Test struct {
 	Name *string `json:"name"`
 }
diff --git a/hack/generator/pkg/jsonast/testdata/AllOf/AllOf_generates_wrapper_type.golden b/hack/generator/pkg/jsonast/testdata/AllOf/AllOf_generates_wrapper_type.golden
index e044ec59b62..d5afcbc32e0 100644
--- a/hack/generator/pkg/jsonast/testdata/AllOf/AllOf_generates_wrapper_type.golden
+++ b/hack/generator/pkg/jsonast/testdata/AllOf/AllOf_generates_wrapper_type.golden
@@ -5,28 +5,32 @@ package v20200101
 
 import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 
-/*Generated from: https://test.test/schemas/2020-01-01/test.json#/definitions/Bar*/
+//Generated from: https://test.test/schemas/2020-01-01/test.json#/definitions/Bar
 type Bar struct {
+
 	// +kubebuilder:validation:Required
 	Size int `json:"size"`
 }
 
-/*Generated from: https://test.test/schemas/2020-01-01/test.json#/definitions/Baz*/
+//Generated from: https://test.test/schemas/2020-01-01/test.json#/definitions/Baz
 type Baz struct {
+
 	// +kubebuilder:validation:Required
 	Enabled bool `json:"enabled"`
 }
 
-/*Generated from: https://test.test/schemas/2020-01-01/test.json#/definitions/Foo*/
+//Generated from: https://test.test/schemas/2020-01-01/test.json#/definitions/Foo
 type Foo struct {
 	Name *string `json:"name"`
 }
 
-/*Generated from: https://test.test/schemas/2020-01-01/test.json*/
+//Generated from: https://test.test/schemas/2020-01-01/test.json
 type Test struct {
+
 	// +kubebuilder:validation:Required
 	Enabled bool    `json:"enabled"`
 	Name    *string `json:"name"`
+
 	// +kubebuilder:validation:Required
 	Size int `json:"size"`
 }
diff --git a/hack/generator/pkg/jsonast/testdata/OneOf/OneOf_collapses_duplicate_named_types.golden b/hack/generator/pkg/jsonast/testdata/OneOf/OneOf_collapses_duplicate_named_types.golden
index 700bf6dbefe..1ba1c17b14c 100644
--- a/hack/generator/pkg/jsonast/testdata/OneOf/OneOf_collapses_duplicate_named_types.golden
+++ b/hack/generator/pkg/jsonast/testdata/OneOf/OneOf_collapses_duplicate_named_types.golden
@@ -5,10 +5,10 @@ package v20200101
 
 import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 
-/*Generated from: https://test.test/schemas/2020-01-01/test.json#/definitions/Foo*/
+//Generated from: https://test.test/schemas/2020-01-01/test.json#/definitions/Foo
 type Foo struct {
 	Name *string `json:"name"`
 }
 
-/*Generated from: https://test.test/schemas/2020-01-01/test.json*/
+//Generated from: https://test.test/schemas/2020-01-01/test.json
 type Test Foo
diff --git a/hack/generator/pkg/jsonast/testdata/OneOf/OneOf_collapses_duplicate_unnamed_types.golden b/hack/generator/pkg/jsonast/testdata/OneOf/OneOf_collapses_duplicate_unnamed_types.golden
index 329bfeebe9f..66316251853 100644
--- a/hack/generator/pkg/jsonast/testdata/OneOf/OneOf_collapses_duplicate_unnamed_types.golden
+++ b/hack/generator/pkg/jsonast/testdata/OneOf/OneOf_collapses_duplicate_unnamed_types.golden
@@ -5,7 +5,7 @@ package v20200101
 
 import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 
-/*Generated from: https://test.test/schemas/2020-01-01/test.json*/
+//Generated from: https://test.test/schemas/2020-01-01/test.json
 type Test struct {
 	Name *string `json:"name"`
 }
diff --git a/hack/generator/pkg/jsonast/testdata/OneOf/OneOf_generates_wrapper_for_inner_properties.golden b/hack/generator/pkg/jsonast/testdata/OneOf/OneOf_generates_wrapper_for_inner_properties.golden
index 5c73c18d917..9b3a30ff67d 100644
--- a/hack/generator/pkg/jsonast/testdata/OneOf/OneOf_generates_wrapper_for_inner_properties.golden
+++ b/hack/generator/pkg/jsonast/testdata/OneOf/OneOf_generates_wrapper_for_inner_properties.golden
@@ -8,18 +8,19 @@ import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
-/*Generated from: https://test.test/schemas/2020-01-01/test.json#/definitions/Bar*/
+//Generated from: https://test.test/schemas/2020-01-01/test.json#/definitions/Bar
 type Bar struct {
+
 	// +kubebuilder:validation:Required
 	Size int `json:"size"`
 }
 
-/*Generated from: https://test.test/schemas/2020-01-01/test.json#/definitions/Foo*/
+//Generated from: https://test.test/schemas/2020-01-01/test.json#/definitions/Foo
 type Foo struct {
 	Name *string `json:"name"`
 }
 
-/*Generated from: https://test.test/schemas/2020-01-01/test.json*/
+//Generated from: https://test.test/schemas/2020-01-01/test.json
 type Test struct {
 	MyBool     *bool           `json:"myBool"`
 	MyString   *string         `json:"myString"`
@@ -27,9 +28,11 @@ type Test struct {
 }
 
 type TestProperties struct {
-	/*Bar: mutually exclusive with all other properties*/
+
+	//Bar: mutually exclusive with all other properties
 	Bar *Bar `json:"bar"`
-	/*Foo: mutually exclusive with all other properties*/
+
+	//Foo: mutually exclusive with all other properties
 	Foo *Foo `json:"foo"`
 }
 
diff --git a/hack/generator/pkg/jsonast/testdata/OneOf/OneOf_generates_wrapper_type_with_marshal_helper.golden b/hack/generator/pkg/jsonast/testdata/OneOf/OneOf_generates_wrapper_type_with_marshal_helper.golden
index 1ec419b29d1..ebd1e35ed58 100644
--- a/hack/generator/pkg/jsonast/testdata/OneOf/OneOf_generates_wrapper_type_with_marshal_helper.golden
+++ b/hack/generator/pkg/jsonast/testdata/OneOf/OneOf_generates_wrapper_type_with_marshal_helper.golden
@@ -8,30 +8,35 @@ import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
-/*Generated from: https://test.test/schemas/2020-01-01/test.json#/definitions/Bar*/
+//Generated from: https://test.test/schemas/2020-01-01/test.json#/definitions/Bar
 type Bar struct {
+
 	// +kubebuilder:validation:Required
 	Size int `json:"size"`
 }
 
-/*Generated from: https://test.test/schemas/2020-01-01/test.json#/definitions/Baz*/
+//Generated from: https://test.test/schemas/2020-01-01/test.json#/definitions/Baz
 type Baz struct {
+
 	// +kubebuilder:validation:Required
 	Enabled bool `json:"enabled"`
 }
 
-/*Generated from: https://test.test/schemas/2020-01-01/test.json#/definitions/Foo*/
+//Generated from: https://test.test/schemas/2020-01-01/test.json#/definitions/Foo
 type Foo struct {
 	Name *string `json:"name"`
 }
 
-/*Generated from: https://test.test/schemas/2020-01-01/test.json*/
+//Generated from: https://test.test/schemas/2020-01-01/test.json
 type Test struct {
-	/*Bar: mutually exclusive with all other properties*/
+
+	//Bar: mutually exclusive with all other properties
 	Bar *Bar `json:"bar"`
-	/*Baz: mutually exclusive with all other properties*/
+
+	//Baz: mutually exclusive with all other properties
 	Baz *Baz `json:"baz"`
-	/*Foo: mutually exclusive with all other properties*/
+
+	//Foo: mutually exclusive with all other properties
 	Foo *Foo `json:"foo"`
 }
 
diff --git a/hack/generator/pkg/jsonast/testdata/OneOf/OneOf_generates_wrapper_type_with_named_properties_from_anonymous_types.golden b/hack/generator/pkg/jsonast/testdata/OneOf/OneOf_generates_wrapper_type_with_named_properties_from_anonymous_types.golden
index 2d26de8e90e..e220643b29a 100644
--- a/hack/generator/pkg/jsonast/testdata/OneOf/OneOf_generates_wrapper_type_with_named_properties_from_anonymous_types.golden
+++ b/hack/generator/pkg/jsonast/testdata/OneOf/OneOf_generates_wrapper_type_with_named_properties_from_anonymous_types.golden
@@ -8,16 +8,19 @@ import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
-/*Generated from: https://test.test/schemas/2020-01-01/test.json#/definitions/Foo*/
+//Generated from: https://test.test/schemas/2020-01-01/test.json#/definitions/Foo
 type Foo int
 
-/*Generated from: https://test.test/schemas/2020-01-01/test.json*/
+//Generated from: https://test.test/schemas/2020-01-01/test.json
 type Test struct {
-	/*Bool1: mutually exclusive with all other properties*/
+
+	//Bool1: mutually exclusive with all other properties
 	Bool1 *bool `json:"bool1"`
-	/*Foo: mutually exclusive with all other properties*/
+
+	//Foo: mutually exclusive with all other properties
 	Foo *Foo `json:"foo"`
-	/*Object2: mutually exclusive with all other properties*/
+
+	//Object2: mutually exclusive with all other properties
 	Object2 *TestObject2 `json:"object2"`
 }
 
diff --git a/hack/generator/pkg/jsonast/testdata/UnreferencedDefinitions/unreferenced_definitions_are_not_generated.golden b/hack/generator/pkg/jsonast/testdata/UnreferencedDefinitions/unreferenced_definitions_are_not_generated.golden
index 329bfeebe9f..66316251853 100644
--- a/hack/generator/pkg/jsonast/testdata/UnreferencedDefinitions/unreferenced_definitions_are_not_generated.golden
+++ b/hack/generator/pkg/jsonast/testdata/UnreferencedDefinitions/unreferenced_definitions_are_not_generated.golden
@@ -5,7 +5,7 @@ package v20200101
 
 import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 
-/*Generated from: https://test.test/schemas/2020-01-01/test.json*/
+//Generated from: https://test.test/schemas/2020-01-01/test.json
 type Test struct {
 	Name *string `json:"name"`
 }
diff --git a/hack/generator/pkg/jsonast/testdata/Validations/Enums_have_required_validation.golden b/hack/generator/pkg/jsonast/testdata/Validations/Enums_have_required_validation.golden
index f120f0f72ad..7ff74635526 100644
--- a/hack/generator/pkg/jsonast/testdata/Validations/Enums_have_required_validation.golden
+++ b/hack/generator/pkg/jsonast/testdata/Validations/Enums_have_required_validation.golden
@@ -5,8 +5,9 @@ package v20200101
 
 import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 
-/*Generated from: https://test.test/schemas/2020-01-01/test.json*/
+//Generated from: https://test.test/schemas/2020-01-01/test.json
 type Test struct {
+
 	// +kubebuilder:validation:Required
 	Color TestColor `json:"color"`
 }
diff --git a/hack/generator/pkg/jsonast/testdata/Validations/Optional_properties_are_pointers.golden b/hack/generator/pkg/jsonast/testdata/Validations/Optional_properties_are_pointers.golden
index 0a30ade3a2f..8cef7615a6f 100644
--- a/hack/generator/pkg/jsonast/testdata/Validations/Optional_properties_are_pointers.golden
+++ b/hack/generator/pkg/jsonast/testdata/Validations/Optional_properties_are_pointers.golden
@@ -5,7 +5,7 @@ package v20200101
 
 import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 
-/*Generated from: https://test.test/schemas/2020-01-01/test.json*/
+//Generated from: https://test.test/schemas/2020-01-01/test.json
 type Test struct {
 	NotRequired *string `json:"notRequired"`
 }
diff --git a/hack/generator/pkg/jsonast/testdata/Validations/Optional_unknown_type_is_generated_as_interface.golden b/hack/generator/pkg/jsonast/testdata/Validations/Optional_unknown_type_is_generated_as_interface.golden
index 7aba78b7a13..d36ef4d0a70 100644
--- a/hack/generator/pkg/jsonast/testdata/Validations/Optional_unknown_type_is_generated_as_interface.golden
+++ b/hack/generator/pkg/jsonast/testdata/Validations/Optional_unknown_type_is_generated_as_interface.golden
@@ -5,7 +5,7 @@ package v20200101
 
 import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 
-/*Generated from: https://test.test/schemas/2020-01-01/test.json*/
+//Generated from: https://test.test/schemas/2020-01-01/test.json
 type Test struct {
 	Foo interface{} `json:"foo"`
 }
diff --git a/hack/generator/pkg/jsonast/testdata/Validations/Required_properties_have_appropriate_comment.golden b/hack/generator/pkg/jsonast/testdata/Validations/Required_properties_have_appropriate_comment.golden
index 33f2abdae17..866f86a6b44 100644
--- a/hack/generator/pkg/jsonast/testdata/Validations/Required_properties_have_appropriate_comment.golden
+++ b/hack/generator/pkg/jsonast/testdata/Validations/Required_properties_have_appropriate_comment.golden
@@ -5,8 +5,9 @@ package v20200101
 
 import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 
-/*Generated from: https://test.test/schemas/2020-01-01/test.json*/
+//Generated from: https://test.test/schemas/2020-01-01/test.json
 type Test struct {
+
 	// +kubebuilder:validation:Required
 	Required string `json:"required"`
 }