more docs for introspection package

benweint · Jun 12, 2024 · 9530519 · 9530519
1 parent 3f0eb48
commit 9530519
Show file tree

Hide file tree

Showing 2 changed files with 24 additions and 0 deletions.
diff --git a/pkg/introspection/toast.go b/pkg/introspection/toast.go
@@ -202,6 +202,16 @@ func makeDefaultValue(t *Type, raw string) (*ast.Value, error) {
 	}, nil
 }
 
+// makeValue parses a raw string representing a GraphQL Value[1]
+// This is useful for handling the __InputValue.defaultValue field[2] in the
+// introspection schema.
+//
+// Since the GraphQL parser we're using doesn't support parsing a Value directly,
+// we have to wrap the value in a dummy query here, providing it as an argument
+// to a non-existent field.
+//
+// [1]: https://spec.graphql.org/October2021/#Value
+// [2]: https://spec.graphql.org/October2021/#sec-The-__InputValue-Type
 func makeValue(raw string) (*ast.Value, error) {
 	src := &ast.Source{
 		Input: fmt.Sprintf("{ f(in: %s) }", raw),

diff --git a/pkg/introspection/types.go b/pkg/introspection/types.go
@@ -8,6 +8,8 @@ type IntrospectionQueryResult struct {
 	Schema Schema `json:"__schema"`
 }
 
+// Schema represents an instance of the __Schema introspection type:
+// https://spec.graphql.org/October2021/#sec-The-__Schema-Type
 type Schema struct {
 	Types            []Type      `json:"types"`
 	QueryType        Type        `json:"queryType,omitempty"`
@@ -16,6 +18,8 @@ type Schema struct {
 	Directives       []Directive `json:"directives,omitempty"`
 }
 
+// Type represents an instance of the __Type introspection type:
+// https://spec.graphql.org/October2021/#sec-The-__Type-Type
 type Type struct {
 	Kind        TypeKind `json:"kind"`
 	Name        string   `json:"name,omitempty"`
@@ -40,6 +44,8 @@ type Type struct {
 	OfType *Type `json:"ofType,omitempty"`
 }
 
+// Directive represents an instance of the __Directive introspection type:
+// https://spec.graphql.org/October2021/#sec-The-__Directive-Type
 type Directive struct {
 	Name         string              `json:"name"`
 	Description  string              `json:"description,omitempty"`
@@ -48,6 +54,8 @@ type Directive struct {
 	IsRepeatable bool                `json:"isRepeatable"`
 }
 
+// Field represents an instance of the __Field introspection type:
+// https://spec.graphql.org/October2021/#sec-The-__Field-Type
 type Field struct {
 	Name              string       `json:"name"`
 	Description       string       `json:"description,omitempty"`
@@ -57,20 +65,25 @@ type Field struct {
 	DeprecationReason string       `json:"deprecationReason"`
 }
 
+// EnumValue represents an instance of the __EnumValue introspection type:
+// https://spec.graphql.org/October2021/#sec-The-__EnumValue-Type
 type EnumValue struct {
 	Name              string `json:"name"`
 	Description       string `json:"description"`
 	IsDeprecated      bool   `json:"isDeprecated"`
 	DeprecationReason string `json:"deprecationReason"`
 }
 
+// InputValue represents an instance of the __InputValue introspection type:
+// https://spec.graphql.org/October2021/#sec-The-__InputValue-Type
 type InputValue struct {
 	Name         string  `json:"name"`
 	Description  string  `json:"description,omitempty"`
 	Type         *Type   `json:"type"`
 	DefaultValue *string `json:"defaultValue,omitempty"`
 }
 
+// TypeKind represents a possible value of the __TypeKind introspection enum.
 type TypeKind string
 
 const (
@@ -84,4 +97,5 @@ const (
 	NonNullKind     = TypeKind("NON_NULL")
 )
 
+// DirectiveLocation represents a possible value of the __DirectiveLocation introspection enum.
 type DirectiveLocation string