feat: go docs to be formatted as JSDocs (#61)

Converts Golang style docs to JSDocs format.

Author: Emyrk

bindings/bindings.go

@@ -2,6 +2,7 @@ package bindings
 
 import (
 	"fmt"
+	"strings"
 
 	"github.com/dop251/goja"
 	"golang.org/x/xerrors"
@@ -733,8 +734,47 @@ func (b *Bindings) CommentGojaObject(comments []SyntheticComment, object *goja.O
 		return nil, err
 	}
 
-	node := object
+	// Group all comments that should be included into a JSDoc block.
+	jsDoc := make([]SyntheticComment, 0)
+	rest := make([]SyntheticComment, 0)
+
 	for _, c := range comments {
+		if !c.DoNotFormat && c.Leading && c.SingleLine {
+			jsDoc = append(jsDoc, c)
+			continue
+		}
+		rest = append(rest, c)
+	}
+
+	// JSDoc comments should be blocked together
+	node := object
+	if len(jsDoc) > 0 {
+		var jsDocComment strings.Builder
+		// JSDoc requires '/**' start and ' */' end. The default synthetic comment only places 1 '*'.
+		// So include the second '*', and start the comment line.
+		jsDocComment.WriteString("*\n *")
+		sep := ""
+		for _, cmt := range jsDoc {
+			jsDocComment.WriteString(sep)
+			jsDocComment.WriteString(cmt.Text)
+			sep = "\n *"
+		}
+		jsDocComment.WriteString("\n ")
+
+		res, err := commentF(goja.Undefined(),
+			node,
+			b.vm.ToValue(true),
+			b.vm.ToValue(false),
+			b.vm.ToValue(jsDocComment.String()),
+			b.vm.ToValue(true),
+		)
+		if err != nil {
+			return nil, xerrors.Errorf("call addSyntheticComment for JSDoc: %w", err)
+		}
+		node = res.ToObject(b.vm)
+	}
+
+	for _, c := range rest {
 		res, err := commentF(goja.Undefined(),
 			node,
 			b.vm.ToValue(c.Leading),

bindings/comments.go

@@ -19,20 +19,24 @@ type SyntheticComment struct {
 	SingleLine      bool
 	Text            string
 	TrailingNewLine bool
+
+	// DoNotFormat indicates this comment should not be attempted to be reformatted.
+	// Guts will attempt to format comments into JSDoc style comments where possible.
+	DoNotFormat bool
 }
 
 type SupportComments struct {
 	comments []SyntheticComment
 }
 
-// LeadingComment is a helper function for the most common type of comment.
 func (s *SupportComments) LeadingComment(text string) {
 	s.AppendComment(SyntheticComment{
 		Leading:    true,
 		SingleLine: true,
 		// All go comments are `// ` prefixed, so add a space.
 		Text:            " " + text,
 		TrailingNewLine: false,
+		DoNotFormat:     true,
 	})
 }
 
@@ -66,5 +70,6 @@ func (s Source) SourceComment() (SyntheticComment, bool) {
 		SingleLine:      true,
 		Text:            fmt.Sprintf(" From %s", s.File),
 		TrailingNewLine: false,
+		DoNotFormat:     true,
 	}, s.File != ""
 }

config/mutations.go

@@ -417,3 +417,24 @@ func isGoEnum(n bindings.Node) (*bindings.Alias, *bindings.UnionType, bool) {
 
 	return al, union, true
 }
+
+// NoJSDocTransform prevents `guts` from reformatting Golang comments to JSDoc.
+// JSDoc comments use `/** */` style multi-line comments.
+func NoJSDocTransform(ts *guts.Typescript) {
+	ts.ForEach(func(key string, node bindings.Node) {
+		walk.Walk(&noJSDocTransformWalker{}, node)
+	})
+}
+
+type noJSDocTransformWalker struct{}
+
+func (v *noJSDocTransformWalker) Visit(node bindings.Node) walk.Visitor {
+	if commentedNode, ok := node.(bindings.Commentable); ok {
+		comments := commentedNode.Comments()
+		for i := range comments {
+			comments[i].DoNotFormat = true
+		}
+	}
+
+	return v
+}

convert_test.go

@@ -130,6 +130,8 @@ func TestGeneration(t *testing.T) {
 						mutations = append(mutations, config.InterfaceToType)
 					case "BiomeLintIgnoreAnyTypeParameters":
 						mutations = append(mutations, config.BiomeLintIgnoreAnyTypeParameters)
+					case "NoJSDocTransform":
+						mutations = append(mutations, config.NoJSDocTransform)
 					default:
 						t.Fatal("unknown mutation, add it to the list:", m)
 					}

testdata/comments/comments.ts

@@ -8,18 +8,26 @@ export interface BlockComment {
 }
 
 // From comments/comments.go
-// CommentedStructure is a struct with a comment.
-//
-// It actually has 2 comments?!
-// TODO: Maybe add a third comment!
+/**
+ * CommentedStructure is a struct with a comment.
+ *
+ * It actually has 2 comments?!
+ * TODO: Maybe add a third comment!
+ */
 export interface CommentedStructure {
     readonly Inline: string; // Field comment
-    // Leading comment
+    /**
+     * Leading comment
+     */
     readonly Leading: string;
     readonly Trailing: string;
-    // Leading comment
+    /**
+     * Leading comment
+     */
     readonly All: string; // Inline comment
-    //  Another leading comment 
+    /**
+     *  Another leading comment
+     */
     readonly Block: string;
     /* Multi
         Line
@@ -29,7 +37,9 @@ export interface CommentedStructure {
 }
 
 // From comments/comments.go
-// Constant is just a value
+/**
+ * Constant is just a value
+ */
 export const Constant = "value"; // An inline note
 
 

testdata/enums/enums.ts

@@ -14,7 +14,9 @@ export enum EnumInt {
 }
 
 // From enums/enums.go
-// EnumSliceType is a slice of string-based enums
+/**
+ * EnumSliceType is a slice of string-based enums
+ */
 export type EnumSliceType = readonly EnumString[];
 
 // From enums/enums.go

testdata/generics/generics.ts

@@ -25,7 +25,9 @@ export interface Complex<C extends Comparable, S extends Single, T extends Custo
 export type Custom = string | boolean | number | number | string[] | (number | null);
 
 // From codersdk/generics.go
-// Dynamic has some dynamic fields.
+/**
+ * Dynamic has some dynamic fields.
+ */
 export interface Dynamic<A extends any, S extends Single> {
     readonly dynamic: Fields<boolean, A, string, S>;
     readonly comparable: boolean | null;
@@ -49,7 +51,9 @@ export interface FieldsDiffOrder<A extends any, C extends Comparable, S extends
 export type Single = string;
 
 // From codersdk/generics.go
-// Static has all generic fields defined in the field
+/**
+ * Static has all generic fields defined in the field
+ */
 export interface Static {
     readonly static: Fields<string, number, number, string>;
 }

testdata/inheritance/inheritance.ts

@@ -21,8 +21,10 @@ export interface FooBarPtr extends Bar, GenBar<string> {
 }
 
 // From codersdk/inheritance.go
-// FooBuzz has a json tag for the embedded
-// See: https://go.dev/play/p/-p6QYmY8mtR
+/**
+ * FooBuzz has a json tag for the embedded
+ * See: https://go.dev/play/p/-p6QYmY8mtR
+ */
 export interface FooBuzz {
     readonly foo: Buzz; // Json tag changes the inheritance
     readonly bazz: string;

testdata/nojsdoc/mutations

@@ -0,0 +1 @@
+NoJSDocTransform

testdata/nojsdoc/nojsdoc.go

@@ -0,0 +1,7 @@
+package nojsdoc
+
+// Commented is a struct that does nothing
+type Commented struct {
+	// Nothing is not very helpful
+	Nothing string
+}