chore: add comments and update readme

Author: Emyrk

README.md

@@ -2,7 +2,7 @@
 
 [![Go Reference](https://pkg.go.dev/badge/github.com/coder/guts.svg)](https://pkg.go.dev/github.com/coder/guts)
 
-`guts` is a tool to convert golang types to typescript for enabling a consistent type definition across the frontend and backend. It is intended to be called and customized as a library, rather than as a command line tool.
+`guts` is a tool to convert golang types to typescript for enabling a consistent type definition across the frontend and backend. It is intended to be called and customized as a library, rather than as a command line executable.
 
 See the [simple example](./example/simple) for a basic usage of the library.
 ```go
@@ -32,17 +32,32 @@ interface SimpleType<T extends Comparable> {
 
 `guts` is a library, not a command line utility. This is to allow configuration with code, and also helps with package resolution.
 
-See the [simple example](./example/simple) for a basic usage of the library.
+See the [simple example](./example/simple) for a basic usage of the library. A larger example can be found in the [Coder repository](https://github.com/coder/coder/blob/a632a841d4f5666c2c1690801f88cd1a1fcffc00/scripts/apitypings/main.go).
 
 ```go
+// Step 1: Create a new Golang parser
+golang, _ := guts.NewGolangParser()
+// Step 2: Configure the parser
+_ = golang.IncludeGenerate("github.com/coder/guts/example/simple")
+// Step 3: Convert the Golang to the typescript AST
+ts, _ := golang.ToTypescript()
+// Step 4: Mutate the typescript AST
+ts.ApplyMutations(
+    config.ExportTypes, // add 'export' to all top level declarations
+)
+// Step 5: Serialize the typescript AST to a string
+output, _ := ts.Serialize()
+fmt.Println(output)
+```
+
 
 # How it works
 
 `guts` first parses a set of golang packages. The Go AST is traversed to find all the types defined in the packages. 
 
 These types are placed into a simple AST that directly maps to the typescript AST.
 
-Using [goja](https://github.com/dop251/goja), these types are then converted to typescript using the typescript compiler API. 
+Using [goja](https://github.com/dop251/goja), these types are then serialized to typescript using the typescript compiler API. 
 
 
 # Generator Opinions
@@ -64,4 +79,4 @@ output, _ := ts.Serialize()
 
 # Helpful notes
 
-An incredible website to visualize the AST of typescript: https://ts-ast-viewer.com/
+An incredible website to visualize the AST of typescript: https://ts-ast-viewer.com/

TODO.md

@@ -2,6 +2,7 @@ package bindings
 
 import (
 	"fmt"
+	"go/token"
 	"go/types"
 
 	"github.com/dop251/goja"
@@ -11,12 +12,16 @@ type Node interface {
 	isNode()
 }
 
+// Identifier is a name given to a variable, function, class, etc.
+// Identifiers should be unique within a package. Package information is
+// included to help with disambiguation in the case of name collisions.
 type Identifier struct {
 	Name    string
 	Package *types.Package
 	Prefix  string
 }
 
+// GoName should be a unique name for the identifier across all Go packages.
 func (i Identifier) GoName() string {
 	if i.PkgName() != "" {
 		return fmt.Sprintf("%s.%s", i.PkgName(), i.Name)
@@ -36,12 +41,16 @@ func (i Identifier) String() string {
 }
 
 // Ref returns the identifier reference to be used in the generated code.
+// This is the identifier to be used in typescript, since all generated code
+// lands in the same namespace.
 func (i Identifier) Ref() string {
 	return i.Prefix + i.Name
 }
 
+// Source is the golang file that an entity is sourced from.
 type Source struct {
-	File string
+	File     string
+	Position token.Position
 }
 
 type HeritageType string
@@ -51,6 +60,8 @@ const (
 	HeritageTypeImplements HeritageType = "implements"
 )
 
+// HeritageClause
+// interface Foo extends Bar, Baz {}
 type HeritageClause struct {
 	Token HeritageType
 	Args  []ExpressionType

bindings/ast.go

@@ -26,6 +26,7 @@ type Interface struct {
 func (*Interface) isNode()            {}
 func (*Interface) isDeclarationType() {}
 
+// PropertySignature is a field in an interface
 type PropertySignature struct {
 	// Name is the field name
 	Name          string
@@ -85,6 +86,9 @@ func Simplify(p []*TypeParameter) ([]*TypeParameter, error) {
 	return params, nil
 }
 
+// VariableStatement is a top level declaration of a variable
+// var foo: string = "bar"
+// const foo: string = "bar"
 type VariableStatement struct {
 	Modifiers    []Modifier
 	Declarations *VariableDeclarationList

bindings/declarations.go

@@ -1,6 +1,10 @@
 package bindings
 
-import "golang.org/x/xerrors"
+import (
+	"fmt"
+
+	"golang.org/x/xerrors"
+)
 
 // ExpressionType
 type ExpressionType interface {
@@ -134,7 +138,15 @@ type OperatorNodeType struct {
 	Type    ExpressionType
 }
 
+// OperatorNode allows adding a keyword to a type
+// Keyword must be "KeyOfKeyword" | "UniqueKeyword" | "ReadonlyKeyword"
 func OperatorNode(keyword LiteralKeyword, node ExpressionType) *OperatorNodeType {
+	switch keyword {
+	case KeywordReadonly, KeywordUnique, KeywordKeyOf:
+	default:
+		// TODO: Would be better to raise some error here.
+		panic(fmt.Sprint("unsupported operator keyword: ", keyword))
+	}
 	return &OperatorNodeType{
 		Keyword: keyword,
 		Type:    node,

bindings/expressions.go

@@ -2,14 +2,20 @@ package guts
 
 import "github.com/coder/guts/bindings"
 
+// Some references are built into either Golang or Typescript.
 var (
+	// builtInComparable is a reference to the 'comparable' type in Golang.
 	builtInComparable = bindings.Identifier{Name: "Comparable"}
-	builtInString     = bindings.Identifier{Name: "string"}
-	builtInNumber     = bindings.Identifier{Name: "number"}
-	builtInBoolean    = bindings.Identifier{Name: "boolean"}
-	builtInRecord     = bindings.Identifier{Name: "Record"}
+	// builtInRecord is a reference to the 'Record' type in Typescript.
+	builtInRecord = bindings.Identifier{Name: "Record"}
 )
 
+// RecordReference creates a reference to the 'Record' type in Typescript.
+// The Record type takes in 2 type parameters, key and value.
+func RecordReference(key, value bindings.ExpressionType) *bindings.ReferenceType {
+	return bindings.Reference(builtInRecord, key, value)
+}
+
 func (ts *Typescript) includeComparable() {
 	// The zzz just pushes it to the end of the sorting.
 	// Kinda strange, but it works.
@@ -18,9 +24,9 @@ func (ts *Typescript) includeComparable() {
 			Name:      builtInComparable,
 			Modifiers: []bindings.Modifier{},
 			Type: bindings.Union(
-				bindings.Reference(builtInString),
-				bindings.Reference(builtInNumber),
-				bindings.Reference(builtInBoolean),
+				ptr(bindings.KeywordString),
+				ptr(bindings.KeywordNumber),
+				ptr(bindings.KeywordBoolean),
 			),
 			Parameters: []*bindings.TypeParameter{},
 			Source:     bindings.Source{},

bindings/parse.go

@@ -8,6 +8,7 @@ import (
 	"github.com/coder/guts/config"
 )
 
+// TODO: Build out a decent cli for this, just for easy experimentation.
 func main() {
 	//ctx := context.Background()
 	gen, err := guts.NewGolangParser()

builtins.go

@@ -0,0 +1,3 @@
+// Package config provides standard configurations for the guts package.
+// These configurations are useful for common use cases.
+package config

cmd/gots/main.go

@@ -786,7 +786,7 @@ func (ts *Typescript) typescriptType(ty types.Type) (parsedType, error) {
 			return parsedType{}, xerrors.Errorf("simplify generics in map: %w", err)
 		}
 		parsed := parsedType{
-			Value:          bindings.Reference(builtInRecord, keyType.Value, valueType.Value),
+			Value:          RecordReference(keyType.Value, valueType.Value),
 			TypeParameters: tp,
 			RaisedComments: append(keyType.RaisedComments, valueType.RaisedComments...),
 		}