Updates to: Controller Actions, Custom Scalars, Code Samples and typos (#16)

* updated docs for attributes, actions, scalars, controller actions, custom scalars

Author: kevin-carroll

docs/advanced/custom-scalars.md

@@ -8,7 +8,7 @@ Scalars are the most basic, fundamental unit of content in GraphQL. It is one of
 
 Enums, being a type of their own, are very straight forward in .NET. Scalars, however; can be anything. For instance, the `Uri` scalar is represented in GraphQL by a string. On the server though, we convert it into a `System.Uri` object, with all the extra features that go along with it.
 
-This can be done for any value that can be represented as a simple string of characters. When you create a scalar you declare its .NET type, provide a resolver that accepts raw data from a query (a `ReadOnlySpan<char>`) and returns the completed scalar value.
+This can be done for any value that can be represented as a simple set of characters. When you create a scalar you declare its .NET type, provide a value resolver that accepts raw data from a query (a `ReadOnlySpan<char>`) and returns the completed scalar value.
 
 Lets say we wanted to build a scalar called `Money` that can handle both an amount and currency symbol. We might accept it in a query like this:
 
@@ -58,7 +58,7 @@ query {
 </div>
 <br/>
 
-The query supplies the data as a quoted string, `"$18.45"`, but our action method receives a `Money` object. Internally, GraphQL senses that the value should be `Money` from the schema definition and invokes the correct graph type to resolve the value and generate the .NET object that can be passed to our action method.
+The query supplies the data as a quoted string, `"$18.45"`, but our action method receives a `Money` object. Internally, GraphQL senses that the value should be `Money` from the schema definition and invokes the correct resolver to parse the value and generate the .NET object that can be passed to our action method.
 
 ## Implement IScalarGraphType
 
@@ -77,13 +77,13 @@ namespace GraphQL.AspNet.Interfaces.TypeSystem
         ScalarValueType ValueType { get; }
         Type ObjectType { get; }
         TypeCollection OtherKnownTypes { get; }
-        IScalarValueResolver SourceResolver { get; }
+        ILeafValueResolver SourceResolver { get; }
         IScalarValueSerializer Serializer { get; }
 
         bool ValidateObject(object item);
     }
 
-    public interface IScalarValueResolver
+    public interface ILeafValueResolver
     {
         object Resolve(ReadOnlySpan<char> data);
     }
@@ -105,27 +105,27 @@ namespace GraphQL.AspNet.Interfaces.TypeSystem
 -   `ValueType`: A set of flags indicating what type of source data, read from a query, this scalar is capable of processing (string, number or boolean). GraphQL will do a preemptive check and if the query document does not supply the data in the correct format it will not attempt to resolve the scalar. Most custom scalars will use `ScalarValueType.String`.
 -   `ObjectType`: The primary, internal type representing the scalar in .NET. In our example above we would set this to `typeof(Money)`.
 -   `OtherKnownTypes`: A collection of other potential types that could be used to represent the scalar in a controller class. For instance, integers can be expressed as `int` or `int?`. Most scalars will provide an empty list (e.g. `TypeCollection.Empty`).
--   `SourceResolver`: An object that implements `IScalarValueResolver` that converts raw input data into the scalar's primary `ObjectType`.
--   `Serializer`: An object that implements `IScalarValueSerializer` that converts the internal representation of the scalar (a class or struct) to a valid graphql scalar (a number, string or boolean).
+-   `SourceResolver`: An object that implements `ILeafValueResolver` which can convert raw input data into the scalar's primary `ObjectType`.
+-   `Serializer`: An object that implements `IScalarValueSerializer` that converts the internal representation of the scalar (a class or struct) to a valid, serialized output (a number, string or boolean).
 -   `ValidateObject(object)`: A method used when validating data returned from a a field resolver. GraphQL will call this method and provide the value from the resolver to determine if its acceptable and should continue resolving child fields.
 
 > `ValidateObject(object)` should not attempt to enforce nullability rules. In general, all scalars should return `true` if the provided object is `null`.
 
-### IScalarValueResolver Members
+### ILeafValueResolver Members
 
 -   `Resolve(ReadOnlySpan<char>)`: A resolver function capable of converting an array of characters into the internal representation of the type.
 
 #### Dealing with Escaped Strings
 
-The span provided to `IScalarValueResolver.Resolve` will be the raw data read from the query document. If the data represents a string, it will be provided in its delimited format. This means being surrounded by quotes as well as containing escaped characters (including unicode characters):
+The span provided to `ILeafValueResolver.Resolve` will be the raw data read from the query document. If the data represents a string, it will be provided in its delimited format. This means being surrounded by quotes as well as containing escaped characters (including escaped unicode characters):
 
 Example string data:
 
 -   `"quoted string"`
 -   `"""triple quoted string"""`
 -   `"With \"\u03A3scaped ch\u03B1racters\""`;
 
-The `StringScalarType` provides a handy static method for converting the data if you don't need to do anything special with it, `StringScalarType.UnescapeAndTrimDelimiters`.
+The `StringScalarType` provides a handy static method for unescaping the data if you don't need to do anything special with it, `StringScalarType.UnescapeAndTrimDelimiters`.
 
 Calling `UnescapeAndTrimDelimiters` with the previous examples produces:
 
@@ -141,17 +141,17 @@ If you throw `UnresolvedValueException` your error message will be delivered ver
 
 ### IScalarValueSerializer Members
 
--   `Serialize(object)`: A serializer that converts the internal representation of the scalar to a [graphql compliant scalar value](https://graphql.github.io/graphql-spec/June2018/#sec-Scalars); a `number`, `string`, `bool` or `null`.
+-   `Serialize(object)`: A serializer that converts the internal representation of the scalar to a [graphql compliant scalar value](https://graphql.github.io/graphql-spec/October2021/#sec-Scalars); a `number`, `string`, `bool` or `null`.
     -   When converting to a number this can be any number value type (int, float, decimal etc.).
 
-> `Serialize(object)` must return a valid graphql scalar type.
+> `Serialize(object)` must return a string, any primative number or a boolean.
 
 Taking a look at the at the serializer for the `Guid` scalar type we can see that while internally the `System.Guid` struct represents the value we convert it to a string when serializing it. Most scalar implementations will serialize to a string.
 
 ```csharp
 public class GuidScalarSerializer : IScalarValueSerializer
 {
-    public override object Serialize(object item)
+    public object Serialize(object item)
     {
         if (item == null)
             return item;
@@ -161,6 +161,8 @@ public class GuidScalarSerializer : IScalarValueSerializer
 }
 ```
 
+> The `Serialize()` method will only be given an object of the approved types for the scalar or null.
+
 ---
 
 The Completed Money Scalar:
@@ -185,7 +187,7 @@ The Completed Money Scalar:
 
         public TypeCollection OtherKnownTypes => TypeCollection.Empty;
 
-        public IScalarValueResolver SourceResolver { get; } = new MoneyScalarTypeResolver();
+        public ILeafValueResolver SourceResolver { get; } = new MoneyLeafTypeResolver();
 
         public IScalarValueSerializer Serializer { get; } = new MoneyScalarTypeSerializer()
 
@@ -198,11 +200,12 @@ The Completed Money Scalar:
         }
     }
 
-    public class MoneyScalarTypeResolver : IScalarValueResolver
+    public class MoneyLeafTypeResolver : ILeafValueResolver
     {
         public object Resolve(ReadOnlySpan<char> data)
         {
-            // example only, more validation code is needed
+            // example only, more validation code is needed to fully validate 
+            // the data
             var sanitizedMoney = StringScalarType.UnescapeAndTrimDelimiters(data);
             if(sanitizedMoney == null || sanitizedMoney.Length < 2)
                 throw new UnresolvedValueException("Money must be at least 2 characters");
@@ -231,9 +234,9 @@ The last step in declaring a scalar is to register it with the runtime. Scalars
 // Startup.cs (other code)
 public void ConfigureServices(IServiceCollection services)
 {
-    // register the scalar to the global provider
+    // register the scalar type to the global provider
     // BEFORE a call to .AddGraphQL()
-    GraphQLProviders.ScalarProvider.RegisterCustomScalar(new MoneyScalarType());
+    GraphQLProviders.ScalarProvider.RegisterCustomScalar(typeof(MoneyScalarType));
 
     services.AddMvc()
             .AddGraphQL();
@@ -242,22 +245,21 @@ public void ConfigureServices(IServiceCollection services)
 
 Since our scalar is, internally, represented by a class, if we don't pre-register it GraphQL will attempt to parse the `Money` class as an object graph type. Once registered as a scalar, any attempt to use `Money` as an object graph type will cause an exception.
 
-## When Developing a Scalar
+## Tips When Developing a Scalar
 
 A few points about designing your scalar:
 
 -   Scalar types are expected to be thread safe.
+-   The runtime will pass a new instance of your scalar graph type to each registered schema. It must be declared with a public, parameterless constructor.
 -   Scalar types should be simple and work in isolation.
     -   The `ReadOnlySpan<char>` provided to the `Resolve()` method should be all the data needed to generate a value, there should be no need to perform side effects or fetch additional data.
-    -   If you have a lot of logic to unpack a string to create your scalar consider using a regular object graph type instead.
--   A scalar type is a singleton instance.
-    -   Scalar types exist for the lifetime of the server instance.
-    -   Scalar types should not track any state or depend on any stateful objects.
--   `IScalarValueResolver.Resolve` must be **FAST**! Since your resolver is used to construct an initial query plan, it'll be called orders of magnitude more often than any controller action method.
+    -   If you have a lot of logic to unpack a string, consider using a regular OBJECT graph type instead.
+-   Scalar types should not track any state or depend on any stateful objects.
+-   `ILeafValueResolver.Resolve` must be **FAST**! Since your resolver is used to construct an initial query plan, it'll be called #orders of magnitude more often than any controller action method.
 
-## Aim for Fewer Scalars
+### Aim for Fewer Scalars
 
-Avoid the urge to start declaring a lot of custom scalars. In fact, chances are that you'll never need to create one. In our example we could have represented our money scalar as an object graph type:
+Avoid the urge to start declaring a lot of custom scalars. In fact, chances are that you'll never need to create one. In our example we could have represented our money scalar as an INPUT_OBJECT graph type:
 
 <div class="sideBySideCode hljs">
 <div>