feat: Apply in-code documentation to generated GraphQL

lib/metadata/metadata.go

@@ -38,16 +38,22 @@ type Metadata struct {
 	Types     TypeMap     `json:"types,omitempty"`
 }
 
+type Docs struct {
+	Lines []string `json:"lines"`
+}
+
 type Function struct {
 	Name       string       `json:"-"`
 	Parameters []*Parameter `json:"parameters,omitempty"`
 	Results    []*Result    `json:"results,omitempty"`
+	Docs       *Docs        `json:"docs,omitempty"`
 }
 
 type TypeDefinition struct {
 	Name   string   `json:"-"`
 	Id     uint32   `json:"id,omitempty"`
 	Fields []*Field `json:"fields,omitempty"`
+	Docs   *Docs    `json:"docs,omitempty"`
 }
 
 type Parameter struct {
@@ -64,6 +70,7 @@ type Result struct {
 type Field struct {
 	Name string `json:"name"`
 	Type string `json:"type"`
+	Docs *Docs  `json:"docs,omitempty"`
 }
 
 func (p *Parameter) UnmarshalJSON(data []byte) error {
@@ -122,9 +129,9 @@ func (m *Metadata) SdkVersion() string {
 func (m *Metadata) GetTypeDefinition(typ string) (*TypeDefinition, error) {
 	switch typ {
 	case "[]byte":
-		return &TypeDefinition{typ, 1, nil}, nil
+		return &TypeDefinition{typ, 1, nil, nil}, nil
 	case "string":
-		return &TypeDefinition{typ, 2, nil}, nil
+		return &TypeDefinition{typ, 2, nil, nil}, nil
 	}
 
 	def, ok := m.Types[typ]

runtime/config/version.go

@@ -14,7 +14,7 @@ import (
 	"strings"
 )
 
-var version string
+var version = "v0.12.7-38-gacb19ff"
 
 func init() {
 	// The "version" variable is set by the makefile using -ldflags when using "make build" or goreleaser.

runtime/graphql/schemagen/schemagen.go

@@ -119,6 +119,7 @@ func transformTypes(types metadata.TypeMap, lti langsupport.LanguageTypeInfo, fo
 		typeDefs[name] = &TypeDefinition{
 			Name:   name,
 			Fields: fields,
+			Docs:   t.Docs,
 		}
 	}
 	return typeDefs, errors
@@ -128,12 +129,14 @@ type FieldDefinition struct {
 	Name       string
 	Arguments  []*ArgumentDefinition
 	ReturnType string
+	Docs       *metadata.Docs
 }
 
 type TypeDefinition struct {
 	Name      string
-	Fields    []*NameTypePair
+	Fields    []*metadata.Field
 	IsMapType bool
+	Docs      *metadata.Docs
 }
 
 type NameTypePair struct {
@@ -145,6 +148,7 @@ type ArgumentDefinition struct {
 	Name    string
 	Type    string
 	Default *any
+	Docs    *metadata.Docs
 }
 
 // TODO: refactor for readability
@@ -179,6 +183,7 @@ func transformFunctions(functions metadata.FunctionMap, inputTypeDefs, resultTyp
 			Name:       fieldName,
 			Arguments:  args,
 			ReturnType: returnType,
+			Docs:       fn.Docs,
 		}
 
 		if isMutation(fn.Name) {
@@ -333,6 +338,11 @@ func writeSchema(buf *bytes.Buffer, queryFields []*FieldDefinition, mutationFiel
 	// write input types
 	for _, t := range inputTypeDefs {
 		buf.WriteByte('\n')
+		if t.Docs != nil {
+			buf.WriteString("\"\"\"\n")
+			buf.WriteString(strings.Join(t.Docs.Lines, "\n"))
+			buf.WriteString("\n\"\"\"\n")
+		}
 		buf.WriteString("input ")
 		buf.WriteString(t.Name)
 		buf.WriteString(" {\n")
@@ -349,10 +359,20 @@ func writeSchema(buf *bytes.Buffer, queryFields []*FieldDefinition, mutationFiel
 	// write result types
 	for _, t := range resultTypeDefs {
 		buf.WriteByte('\n')
+		if t.Docs != nil {
+			buf.WriteString("\"\"\"\n")
+			buf.WriteString(strings.Join(t.Docs.Lines, "\n"))
+			buf.WriteString("\n\"\"\"\n")
+		}
 		buf.WriteString("type ")
 		buf.WriteString(t.Name)
 		buf.WriteString(" {\n")
 		for _, f := range t.Fields {
+			if f.Docs != nil {
+				buf.WriteString("  \"\"\"\n  ")
+				buf.WriteString(strings.Join(f.Docs.Lines, "\n  "))
+				buf.WriteString("  \n  \"\"\"\n")
+			}
 			buf.WriteString("  ")
 			buf.WriteString(f.Name)
 			buf.WriteString(": ")
@@ -364,6 +384,11 @@ func writeSchema(buf *bytes.Buffer, queryFields []*FieldDefinition, mutationFiel
 }
 
 func writeField(buf *bytes.Buffer, field *FieldDefinition) {
+	if field.Docs != nil {
+		buf.WriteString("  \"\"\"\n  ")
+		buf.WriteString(strings.Join(field.Docs.Lines, "\n  "))
+		buf.WriteString("  \n  \"\"\"\n")
+	}
 	buf.WriteString("  ")
 	buf.WriteString(field.Name)
 	if len(field.Arguments) > 0 {
@@ -421,7 +446,7 @@ func convertResults(results []*metadata.Result, lti langsupport.LanguageTypeInfo
 		return convertType(results[0].Type, lti, typeDefs, false, false)
 	}
 
-	fields := make([]*NameTypePair, len(results))
+	fields := make([]*metadata.Field, len(results))
 	for i, r := range results {
 		name := r.Name
 		if name == "" {
@@ -433,7 +458,7 @@ func convertResults(results []*metadata.Result, lti langsupport.LanguageTypeInfo
 			return "", err
 		}
 
-		fields[i] = &NameTypePair{
+		fields[i] = &metadata.Field{
 			Name: name,
 			Type: typ,
 		}
@@ -443,7 +468,7 @@ func convertResults(results []*metadata.Result, lti langsupport.LanguageTypeInfo
 	return t, nil
 }
 
-func getTypeForFields(fields []*NameTypePair, typeDefs map[string]*TypeDefinition) string {
+func getTypeForFields(fields []*metadata.Field, typeDefs map[string]*TypeDefinition) string {
 	// see if an existing type already matches
 	for _, t := range typeDefs {
 		if len(t.Fields) != len(fields) {
@@ -475,20 +500,22 @@ func getTypeForFields(fields []*NameTypePair, typeDefs map[string]*TypeDefinitio
 	return newType(name, fields, typeDefs)
 }
 
-func convertFields(fields []*metadata.Field, lti langsupport.LanguageTypeInfo, typeDefs map[string]*TypeDefinition, forInput bool) ([]*NameTypePair, error) {
+func convertFields(fields []*metadata.Field, lti langsupport.LanguageTypeInfo, typeDefs map[string]*TypeDefinition, forInput bool) ([]*metadata.Field, error) {
 	if len(fields) == 0 {
 		return nil, nil
 	}
 
-	results := make([]*NameTypePair, len(fields))
+	results := make([]*metadata.Field, len(fields))
 	for i, f := range fields {
 		t, err := convertType(f.Type, lti, typeDefs, true, forInput)
 		if err != nil {
 			return nil, err
 		}
-		results[i] = &NameTypePair{
+
+		results[i] = &metadata.Field{
 			Name: f.Name,
 			Type: t,
+			Docs: f.Docs,
 		}
 	}
 	return results, nil
@@ -633,7 +660,10 @@ func convertType(typ string, lti langsupport.LanguageTypeInfo, typeDefs map[stri
 			typeName += "Input"
 		}
 
-		newMapType(typeName, []*NameTypePair{{"key", kt}, {"value", vt}}, typeDefs)
+		newMapType(typeName, []*metadata.Field{
+			{Name: "key", Type: kt, Docs: nil},
+			{Name: "value", Type: vt, Docs: nil},
+		}, typeDefs)
 
 		// The map is represented as a list of the pair type.
 		// The list might be nullable, but the pair type within the list is always non-nullable.
@@ -675,7 +705,7 @@ func newScalar(name string, typeDefs map[string]*TypeDefinition) string {
 	return newType(name, nil, typeDefs)
 }
 
-func newType(name string, fields []*NameTypePair, typeDefs map[string]*TypeDefinition) string {
+func newType(name string, fields []*metadata.Field, typeDefs map[string]*TypeDefinition) string {
 	if _, ok := typeDefs[name]; !ok {
 		typeDefs[name] = &TypeDefinition{
 			Name:   name,
@@ -685,7 +715,7 @@ func newType(name string, fields []*NameTypePair, typeDefs map[string]*TypeDefin
 	return name
 }
 
-func newMapType(name string, fields []*NameTypePair, typeDefs map[string]*TypeDefinition) string {
+func newMapType(name string, fields []*metadata.Field, typeDefs map[string]*TypeDefinition) string {
 	if _, ok := typeDefs[name]; !ok {
 		typeDefs[name] = &TypeDefinition{
 			Name:      name,

sdk/assemblyscript/examples/http/assembly/index.ts

@@ -105,4 +105,4 @@ export function createGithubIssue(
 
   // The response will contain the issue data, including the URL of the issue on GitHub.
   return response.json<Issue>();
-}
+}