fix: handle fields' multi-line comments

renderer/asciidoctor.go

@@ -143,7 +143,17 @@ func (adr *AsciidoctorRenderer) RenderAnchorID(id string) string {
 }
 
 func (adr *AsciidoctorRenderer) RenderFieldDoc(text string) string {
-	// escape the pipe character, which has special meaning for asciidoc as a way to format tables,
-	// so that including | in a comment does not result in wonky tables
-	return strings.ReplaceAll(text, "|", "\\|")
+	// Escape the pipe character, which has special meaning for asciidoc as a way to format tables,
+	// so that including | in a comment does not result in wonky tables.
+	out := strings.ReplaceAll(text, "|", "\\|")
+
+	// Trim any leading and trailing whitespace from each line.
+	lines := strings.Split(out, "\n")
+	for i := range lines {
+		lines[i] = strings.TrimSpace(lines[i])
+	}
+
+	// Replace newlines with hard line breaks so that newlines are rendered as expected.
+	// See: https://docs.asciidoctor.org/asciidoc/latest/blocks/hard-line-breaks
+	return strings.Join(lines, " +\n\n")
 }

renderer/markdown.go

@@ -78,6 +78,7 @@ func (m *MarkdownRenderer) ToFuncMap() template.FuncMap {
 		"SafeID":             m.SafeID,
 		"ShouldRenderType":   m.ShouldRenderType,
 		"TypeID":             m.TypeID,
+		"RenderFieldDoc":     m.RenderFieldDoc,
 	}
 }
 
@@ -140,3 +141,12 @@ func (m *MarkdownRenderer) RenderExternalLink(link, text string) string {
 func (m *MarkdownRenderer) RenderGVLink(gv types.GroupVersionDetails) string {
 	return m.RenderLocalLink(gv.GroupVersionString())
 }
+
+func (m *MarkdownRenderer) RenderFieldDoc(text string) string {
+	// Escape the pipe character, which has special meaning for Markdown as a way to format tables
+	// so that including | in a comment does not result in wonky tables.
+	out := strings.ReplaceAll(text, "|", "\\|")
+
+	// Replace newlines with 2 line breaks so that they don't break the Markdown table formatting.
+	return strings.ReplaceAll(out, "\n", "<br /><br />")
+}

templates/markdown/type_members.tpl

@@ -3,6 +3,6 @@
 {{- if eq $field.Name "metadata" -}}
 Refer to Kubernetes API documentation for fields of `metadata`.
 {{- else -}}
-{{ $field.Doc }}
+{{ markdownRenderFieldDoc $field.Doc }}
 {{- end -}}
 {{- end -}}

test/api/v1/guestbook_types.go

@@ -77,7 +77,9 @@ type GuestbookEntry struct {
 	Name string `json:"name,omitempty"`
 	// Time of entry
 	Time metav1.Time `json:"time,omitempty"`
-	// Comment by guest
+	// Comment by guest. This can be a multi-line comment.
+	//
+	// Just like this one.
 	Comment string `json:"comment,omitempty"`
 	// Rating provided by the guest
 	Rating Rating `json:"rating,omitempty"`

test/expected.asciidoc

@@ -100,7 +100,9 @@ GuestbookEntry defines an entry in a guest book.
 | Field | Description
 | *`name`* __string__ | Name of the guest (pipe \| should be escaped)
 | *`time`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#time-v1-meta[$$Time$$]__ | Time of entry
-| *`comment`* __string__ | Comment by guest
+| *`comment`* __string__ | Comment by guest. This can be a multi-line comment. +
+
+Just like this one.
 | *`rating`* __xref:{anchor_prefix}-github-com-elastic-crd-ref-docs-api-v1-rating[$$Rating$$]__ | Rating provided by the guest
 |===
 

test/expected.md

@@ -82,9 +82,9 @@ _Appears in:_
 
 | Field | Description |
 | --- | --- |
-| `name` _string_ | Name of the guest (pipe | should be escaped) |
+| `name` _string_ | Name of the guest (pipe \| should be escaped) |
 | `time` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#time-v1-meta)_ | Time of entry |
-| `comment` _string_ | Comment by guest |
+| `comment` _string_ | Comment by guest. This can be a multi-line comment. <br /><br /> Just like this one. |
 | `rating` _[Rating](#rating)_ | Rating provided by the guest |