Apply in-code documentation to generated GraphQL (#519)

Co-authored-by: Matt Johnson-Pint <[email protected]>

Author: JairusSW

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## UNRELEASED - Runtime
 
+- feat: Apply in-code documentation to generated GraphQL [#519](https://github.com/hypermodeinc/modus/pull/519)
 - feat: Reduce logger output during development [#576](https://github.com/hypermodeinc/modus/pull/576)
 - chore: Trigger internal release pipeline at the end of the release-runtime workflow [#577](https://github.com/hypermodeinc/modus/pull/577)
 - feat: Add API explorer to runtime [#578](https://github.com/hypermodeinc/modus/pull/578)

lib/metadata/metadata.go

@@ -34,16 +34,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 {
@@ -60,6 +66,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 {
@@ -118,9 +125,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/graphql/schemagen/schemagen.go

@@ -118,10 +118,16 @@ func transformTypes(types metadata.TypeMap, lti langsupport.LanguageTypeInfo, fo
 			continue
 		}
 
-		typeDefs[name] = &TypeDefinition{
+		typeDef := &TypeDefinition{
 			Name:   name,
 			Fields: fields,
 		}
+
+		if t.Docs != nil {
+			typeDef.DocLines = t.Docs.Lines
+		}
+
+		typeDefs[name] = typeDef
 	}
 	return typeDefs, errors
 }
@@ -131,12 +137,14 @@ type FieldDefinition struct {
 	Type      string
 	Arguments []*ArgumentDefinition
 	Function  string
+	DocLines  []string
 }
 
 type TypeDefinition struct {
 	Name      string
 	Fields    []*FieldDefinition
 	IsMapType bool
+	DocLines  []string
 }
 
 type ArgumentDefinition struct {
@@ -186,6 +194,10 @@ func transformFunctions(functions metadata.FunctionMap, inputTypeDefs, resultTyp
 			Function:  fn.Name,
 		}
 
+		if fn.Docs != nil {
+			field.DocLines = fn.Docs.Lines
+		}
+
 		if filter(field) {
 			if isMutation(fn.Name) {
 				mutationFields = append(mutationFields, field)
@@ -329,14 +341,34 @@ func writeSchema(buf *bytes.Buffer, root *RootObjects, scalarTypes []string, inp
 			buf.WriteByte('\n')
 		}
 	}
-
 	// write input types
 	for _, t := range inputTypeDefs {
 		buf.WriteByte('\n')
+
+		if len(t.DocLines) > 0 {
+			buf.WriteString("\"\"\"\n")
+			for _, line := range t.DocLines {
+				buf.WriteString(line)
+				buf.WriteByte('\n')
+			}
+			buf.WriteString("\"\"\"\n")
+		}
+
 		buf.WriteString("input ")
 		buf.WriteString(t.Name)
 		buf.WriteString(" {\n")
 		for _, f := range t.Fields {
+
+			if len(f.DocLines) > 0 {
+				buf.WriteString("  \"\"\"\n")
+				for _, line := range f.DocLines {
+					buf.WriteString("  ")
+					buf.WriteString(line)
+					buf.WriteByte('\n')
+				}
+				buf.WriteString("  \"\"\"\n")
+			}
+
 			buf.WriteString("  ")
 			buf.WriteString(f.Name)
 			buf.WriteString(": ")
@@ -349,10 +381,31 @@ func writeSchema(buf *bytes.Buffer, root *RootObjects, scalarTypes []string, inp
 	// write result types
 	for _, t := range resultTypeDefs {
 		buf.WriteByte('\n')
+
+		if len(t.DocLines) > 0 {
+			buf.WriteString("\"\"\"\n")
+			for _, line := range t.DocLines {
+				buf.WriteString(line)
+				buf.WriteByte('\n')
+			}
+			buf.WriteString("\"\"\"\n")
+		}
+
 		buf.WriteString("type ")
 		buf.WriteString(t.Name)
 		buf.WriteString(" {\n")
 		for _, f := range t.Fields {
+
+			if len(f.DocLines) > 0 {
+				buf.WriteString("  \"\"\"\n")
+				for _, line := range f.DocLines {
+					buf.WriteString("  ")
+					buf.WriteString(line)
+					buf.WriteByte('\n')
+				}
+				buf.WriteString("  \"\"\"\n")
+			}
+
 			buf.WriteString("  ")
 			buf.WriteString(f.Name)
 			buf.WriteString(": ")
@@ -364,6 +417,17 @@ func writeSchema(buf *bytes.Buffer, root *RootObjects, scalarTypes []string, inp
 }
 
 func writeField(buf *bytes.Buffer, field *FieldDefinition) {
+
+	if len(field.DocLines) > 0 {
+		buf.WriteString("  \"\"\"\n")
+		for _, line := range field.DocLines {
+			buf.WriteString("  ")
+			buf.WriteString(line)
+			buf.WriteByte('\n')
+		}
+		buf.WriteString("  \"\"\"\n")
+	}
+
 	buf.WriteString("  ")
 	buf.WriteString(field.Name)
 	if len(field.Arguments) > 0 {
@@ -486,10 +550,17 @@ func convertFields(fields []*metadata.Field, lti langsupport.LanguageTypeInfo, t
 		if err != nil {
 			return nil, err
 		}
-		results[i] = &FieldDefinition{
+
+		fieldDef := &FieldDefinition{
 			Name: f.Name,
 			Type: t,
 		}
+
+		if f.Docs != nil {
+			fieldDef.DocLines = f.Docs.Lines
+		}
+
+		results[i] = fieldDef
 	}
 	return results, nil
 }

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

@@ -6,17 +6,23 @@
 
 import { Person } from "./person";
 
-// This function adds two 32-bit signed integers together, and returns the result.
+/**
+ * Adds two integers together, and returns the result.
+ */
 export function add(a: i32, b: i32): i32 {
   return a + b;
 }
 
-// This function takes a first name and a last name, and concatenates them to returns a full name.
+/**
+ * Combines the first and last name of a person, and returns the full name.
+ */
 export function getFullName(firstName: string, lastName: string): string {
   return `${firstName} ${lastName}`;
 }
 
-// This function makes a list of people, and returns it.
+/**
+ * Gets a list of people.
+ */
 export function getPeople(): Person[] {
   return [
     new Person("Bob", "Smith"),
@@ -25,15 +31,19 @@ export function getPeople(): Person[] {
   ];
 }
 
-// This function returns a random person from the list of people.
+/**
+ * Gets a random person from the list of people.
+ */
 export function getRandomPerson(): Person {
   const people = getPeople();
   const index = <i32>Math.floor(Math.random() * people.length);
   const person = people[index];
   return person;
 }
 
-// This function demonstrates various ways to log messages and errors.
+/**
+ * Demonstrates logging error messages at different levels.
+ */
 export function testErrors(): void {
   // This is a simple log message. It has no level.
   console.log("This is a simple log message.");

sdk/assemblyscript/examples/simple/assembly/person.ts

@@ -7,9 +7,24 @@
 // This class is used in the examples.
 // It is separated just to demonstrated how to use multiple files.
 // Note, this is just one way to define a class in AssemblyScript.
+
+/**
+ * A simple object representing a person.
+ */
 export class Person {
+  /**
+   * The first name of the person.
+   */
   firstName: string;
+
+  /**
+   * The last name of the person.
+   */
   lastName: string;
+
+  /**
+   * The full name of the person.
+   */
   fullName: string;
 
   constructor(firstName: string, lastName: string) {