feat: Add top-level comment_pretty_doc config option

This commit introduces a new configuration option which can be used
to enable or disable post-processing of the comment/description.
This is useful for providing the description as a comment verbatim.

Signed-off-by: Alexander Jung <alex@nder.sh>

Author: nderjung

gen/generator.go

@@ -73,6 +73,8 @@ func NewGenerator(spec *ogen.Spec, opts Options) (*Generator, error) {
 
 	// Set the comment line limit for pretty documentation.
 	ir.SetLineLimit(opts.Generator.CommentLineLimit)
+	// Set whether to use pretty documentation.
+	ir.SetPrettyDoc(opts.Generator.CommentPrettyDoc)
 
 	var external jsonschema.ExternalResolver
 	if opts.Parser.AllowRemote {

gen/ir/description.go

@@ -11,6 +11,9 @@ import (
 // Global line limit, can be configured via SetLineLimit.
 var lineLimit = 100
 
+// Global flag to enable or disable pretty documentation.
+var prettyDocEnabled = true
+
 // SetLineLimit sets the maximum width of a comment line before it is wrapped.
 // Use a negative value to disable line wrapping altogether.
 func SetLineLimit(limit int) {
@@ -27,6 +30,16 @@ func GetLineLimit() int {
 	return lineLimit
 }
 
+// SetPrettyDoc enables or disables pretty documentation.
+func SetPrettyDoc(enabled bool) {
+	prettyDocEnabled = enabled
+}
+
+// IsPrettyDocEnabled returns whether pretty documentation is enabled.
+func IsPrettyDocEnabled() bool {
+	return prettyDocEnabled
+}
+
 func splitLine(s string, limit int) (r []string) {
 	// If limit is negative, don't split lines.
 	if limit < 0 {
@@ -68,6 +81,25 @@ func splitLine(s string, limit int) (r []string) {
 }
 
 func prettyDoc(s, deprecation string) (r []string) {
+	// If pretty documentation is disabled, return the comment as-is
+	if !prettyDocEnabled {
+		// Just split by newlines.
+		for _, line := range strings.Split(s, "\n") {
+			r = append(r, line)
+		}
+
+		// Add deprecation notice if provided
+		if deprecation != "" {
+			if len(r) > 0 {
+				// Insert empty line between description and deprecated notice.
+				r = append(r, "")
+			}
+			r = append(r, deprecation)
+		}
+
+		return r
+	}
+
 	// Original pretty documentation behavior
 	// TODO(tdakkota): basic common mark rendering?
 	for _, line := range strings.Split(s, "\n") {

gen/ir/description_flag_test.go

@@ -0,0 +1,28 @@
+package ir
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestPrettyDocEnabledFlag(t *testing.T) {
+	// Save original state to restore later
+	originalState := prettyDocEnabled
+
+	// Test with pretty documentation enabled
+	SetPrettyDoc(true)
+	require.True(t, IsPrettyDocEnabled())
+	doc := "   this is a test.   "
+	prettyResult := prettyDoc(doc, "")
+	require.Equal(t, "This is a test.", prettyResult[0])
+
+	// Test with pretty documentation disabled
+	SetPrettyDoc(false)
+	require.False(t, IsPrettyDocEnabled())
+	verbatimResult := prettyDoc(doc, "")
+	require.Equal(t, "   this is a test.   ", verbatimResult[0])
+
+	// Restore original state
+	SetPrettyDoc(originalState)
+}

gen/options.go

@@ -161,6 +161,8 @@ type GenerateOptions struct {
 	IgnoreNotImplemented []string `json:"ignore_not_implemented" yaml:"ignore_not_implemented"`
 	// NotImplementedHook is hook for ErrNotImplemented errors.
 	NotImplementedHook func(name string, err error) `json:"-" yaml:"-"`
+	// CommentPrettyDoc enables or disables pretty documentation for comments.
+	CommentPrettyDoc bool `json:"comment_pretty_doc" yaml:"comment_pretty_doc"`
 	// CommentLineLimit sets the maximum width of a comment line before it is
 	// wrapped.  -1 disables line wrapping altogether.
 	CommentLineLimit int `json:"comment_line_limit" yaml:"comment_line_limit"`