From bef9c8bf3a2d7d63531e4bf9540d550977289a5c Mon Sep 17 00:00:00 2001
From: Luke Cawood <luke.cawood@99designs.com>
Date: Thu, 13 Aug 2020 17:26:49 +1000
Subject: [PATCH] Add comments and docs for pointer scalars

---
 codegen/config/binder.go          |  6 +++---
 docs/content/reference/scalars.md | 12 +++++++-----
 2 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/codegen/config/binder.go b/codegen/config/binder.go
index 514ccc6742e..2be7b7bdd6b 100644
--- a/codegen/config/binder.go
+++ b/codegen/config/binder.go
@@ -166,8 +166,8 @@ func (b *Binder) PointerTo(ref *TypeReference) *TypeReference {
 type TypeReference struct {
 	Definition  *ast.Definition
 	GQL         *ast.Type
-	GO          types.Type
-	Target      types.Type
+	GO          types.Type  // Type of the field being bound. Could be a pointer or a value type of Target.
+	Target      types.Type  // The actual type that we know how to bind to. May require pointer juggling when traversing to fields.
 	CastType    types.Type  // Before calling marshalling functions cast from/to this base type
 	Marshaler   *types.Func // When using external marshalling functions this will point to the Marshal function
 	Unmarshaler *types.Func // When using external marshalling functions this will point to the Unmarshal function
@@ -357,7 +357,7 @@ func (b *Binder) TypeReference(schemaType *ast.Type, bindTarget types.Type) (ret
 			ref.GO = obj.Type()
 			ref.IsMarshaler = true
 		} else if underlying := basicUnderlying(obj.Type()); def.IsLeafType() && underlying != nil && underlying.Kind() == types.String {
-			// Special case for named types wrapping strings. Used by default enum implementations.
+			// TODO delete before v1. Backwards compatibility case for named types wrapping strings (see #595)
 
 			ref.GO = obj.Type()
 			ref.CastType = underlying
diff --git a/docs/content/reference/scalars.md b/docs/content/reference/scalars.md
index eff8b8cf3b0..9bda307f553 100644
--- a/docs/content/reference/scalars.md
+++ b/docs/content/reference/scalars.md
@@ -60,7 +60,6 @@ package mypkg
 import (
 	"fmt"
 	"io"
-	"strings"
 )
 
 type YesNo bool
@@ -69,7 +68,7 @@ type YesNo bool
 func (y *YesNo) UnmarshalGQL(v interface{}) error {
 	yes, ok := v.(string)
 	if !ok {
-		return fmt.Errorf("points must be strings")
+		return fmt.Errorf("YesNo must be a string")
 	}
 
 	if yes == "yes" {
@@ -90,7 +89,7 @@ func (y YesNo) MarshalGQL(w io.Writer) {
 }
 ```
 
-and then in .gqlgen.yml point to the name without the Marshal|Unmarshal in front:
+and then wire up the type in .gqlgen.yml or via directives like normal:
 
 ```yaml
 models:
@@ -100,8 +99,8 @@ models:
 
 ## Custom scalars with third party types
 
-Sometimes you cant add methods to a type because its in another repo, part of the standard
-library (eg string or time.Time). To do this we can build an external marshaler:
+Sometimes you are unable to add add methods to a type - perhaps you don't own the type, or it is part of the standard
+library (eg string or time.Time). To support this we can build an external marshaler:
 
 ```go
 package mypkg
@@ -147,6 +146,9 @@ models:
     model: github.com/me/mypkg.MyCustomBooleanScalar
 ```
 
+**Note:** you also can un/marshal to pointer types via this approach, simply accept a pointer in your
+`Marshal...` func and return one in your `Unmarshal...` func.
+
 See the [example/scalars](https://github.com/99designs/gqlgen/tree/master/example/scalars) package for more examples.
 
 ## Unmarshaling Errors