Split long doc strings over multiple lines (#249)

The OpenAPI spec concatenates some multi-line doc comments in the
original Rust code into a single long line. We write these long lines
verbatim into the Go source we generate, and some are sufficiently long
that viewing the full comment requires [scrolling sideways on
pkg.go.dev](https://pkg.go.dev/github.com/oxidecomputer/oxide.go@v0.1.0-beta9/oxide#InternetGatewayCreate).

Add a helper function to split long doc strings into lines of roughly
100 characters and apply it to the `Description` of our generated paths
and types.

Closes #248

Author: wfchandler

internal/generate/paths.go

@@ -175,7 +175,7 @@ func buildMethod(f *os.File, spec *openapi3.T, method string, path string, o *op
 	sanitisedDescription := strings.ReplaceAll(o.Description, "\n", "\n// ")
 
 	config := methodTemplate{
-		Description:     sanitisedDescription,
+		Description:     splitDocString(sanitisedDescription),
 		HTTPMethod:      method,
 		FunctionName:    methodName,
 		WrappedFunction: ogmethodName,
@@ -278,6 +278,33 @@ func cleanPath(path string) string {
 	return strings.Replace(path, "}", "}}", -1)
 }
 
+// splitDocString inserts newlines into doc comments at approximately 100 character intervals.
+func splitDocString(s string) string {
+	var (
+		out     strings.Builder
+		written int
+	)
+
+	for _, subStr := range strings.SplitAfter(s, " ") {
+		if written > 100 {
+			// Remove trailing space if inserting a newline.
+			out.WriteString(strings.TrimSuffix(subStr, " "))
+			out.WriteString("\n// ")
+			written = 0
+
+			continue
+		}
+
+		ct, _ := out.WriteString(subStr)
+		written += ct
+
+		if strings.Contains(subStr, "\n") {
+			written = 0
+		}
+	}
+	return out.String()
+}
+
 func writeTpl(f *os.File, config methodTemplate) error {
 	var t *template.Template
 	var err error

internal/generate/test_utils/types_output

@@ -11,7 +11,8 @@ type DiskCreate struct {
 	DiskSource DiskSource `json:"disk_source,omitempty" yaml:"disk_source,omitempty"`
 }
 
-// DiskIdentifier is parameters for the [`Disk`](omicron_common::api::external::Disk) to be attached or detached to an instance
+// DiskIdentifier is parameters for the [`Disk`](omicron_common::api::external::Disk) to be attached or
+// detached to an instance
 type DiskIdentifier struct {
 	Name Name `json:"name,omitempty" yaml:"name,omitempty"`
 }

internal/generate/test_utils/types_output_expected

@@ -11,7 +11,8 @@ type DiskCreate struct {
 	DiskSource DiskSource `json:"disk_source,omitempty" yaml:"disk_source,omitempty"`
 }
 
-// DiskIdentifier is parameters for the [`Disk`](omicron_common::api::external::Disk) to be attached or detached to an instance
+// DiskIdentifier is parameters for the [`Disk`](omicron_common::api::external::Disk) to be attached or
+// detached to an instance
 type DiskIdentifier struct {
 	Name Name `json:"name,omitempty" yaml:"name,omitempty"`
 }

internal/generate/types.go

@@ -348,14 +348,14 @@ func writeTypes(f *os.File, typeCollection []TypeTemplate, typeValidationCollect
 			continue
 		}
 
-		fmt.Fprintf(f, "%s\n", tt.Description)
+		fmt.Fprintf(f, "%s\n", splitDocString(tt.Description))
 		fmt.Fprintf(f, "type %s %s", tt.Name, tt.Type)
 		if tt.Fields != nil {
 			fmt.Fprint(f, " {\n")
 			for _, ft := range tt.Fields {
 				if ft.Description != "" {
 					// TODO: Double check about the "//"
-					fmt.Fprintf(f, "\t%s\n", ft.Description)
+					fmt.Fprintf(f, "\t%s\n", splitDocString(ft.Description))
 				}
 				fmt.Fprintf(f, "\t%s %s %s\n", ft.Name, ft.Type, ft.SerializationInfo)
 			}
@@ -398,7 +398,7 @@ func writeTypes(f *os.File, typeCollection []TypeTemplate, typeValidationCollect
 			continue
 		}
 
-		fmt.Fprintf(f, "%s\n", et.Description)
+		fmt.Fprintf(f, "%s\n", splitDocString(et.Description))
 		fmt.Fprintf(f, "%s %s %s\n\n", et.ValueType, et.Name, et.Value)
 	}
 }