Added Missing Directive Attributes and Clarified content (#18)

* updated attributes, actions, scalars, controller actions
* updated custom scalars documentation
* Added missing directive attributes
* Typos and code sample updates
* word choice updates to several controller related docs

Author: kevin-carroll

docs/controllers/authorization.md

@@ -4,6 +4,8 @@ title: Authorization
 sidebar_label: Authorization
 ---
 
+## Quick Examples 
+
 If you've wired up ASP.NET authorization before, you'll likely familiar with the `[Authorize]` attribute and how its used to enforce security. GraphQL ASP.NET works the same way.
 
 ```csharp
@@ -43,7 +45,7 @@ public class BakeryController : GraphController
 }
 ```
 
-GraphQL supports nested checks at Controller and Action levels.
+This library supports nested policy and role checks at Controller and Action levels.
 
 ```csharp
 // BakeryController.cs
@@ -76,9 +78,9 @@ public class BakeryController : GraphController
 }
 ```
 
-## GraphQL Uses IAuthorizationService
+## Use of IAuthorizationService
 
-Under the hood, GraphQL taps into the your `IServiceProvider` to obtain a reference to the `IAuthorizationService` that gets created when you configure `.AddAuthorization()`. Take a peek at the GraphQL FieldAuthorizer in the source code for the full picture.
+Under the hood, GraphQL taps into your `IServiceProvider` to obtain a reference to the `IAuthorizationService` that gets created when you configure `.AddAuthorization()` for policy enforcement rules. Take a look at the [Field Authorization](https://github.com/graphql-aspnet/graphql-aspnet/blob/master/src/graphql-aspnet/Middleware/FieldSecurity/Components/FieldAuthorizationMiddleware.cs) Middleware Component for the full picture.
 
 ## When does Authorization Occur?
 
@@ -88,7 +90,7 @@ _The Default "per field" Authorization workflow_
 
 ---
 
-In the diagram above we can see that user authorization in GraphQL ASP.NET makes use of the result from [ASP.NET's security pipeline](https://docs.microsoft.com/en-us/aspnet/core/security/authorization/introduction?view=aspnetcore-3.0) but makes no attempt to interact with it. Whether you use Kerberos tokens, OAUTH2, username/password, API tokens or if you support 2-factor authentication or one-time-use passwords, GraphQL doesn't care. The entirety of your authentication and authorization pipeline is executed completely before GraphQL gets involved.
+In the diagram above we can see that user authorization in GraphQL ASP.NET makes use of the result from [ASP.NET's security pipeline](https://docs.microsoft.com/en-us/aspnet/core/security/authorization/introduction) but makes no attempt to interact with it. Whether you use Kerberos tokens, OAUTH2, username/password, API tokens or if you support 2-factor authentication or one-time-use passwords, GraphQL doesn't care. The entirety of your authentication and authorization pipeline is executed by GraphQL, no special arrangements or configuration is needed.
 
 > GraphQL ASP.NET draws from your configured authentication/authorization solution.
 
@@ -98,7 +100,7 @@ Null propagation rules still apply to unauthorized fields meaning if the field c
 
 By default, a single unauthorized result does not necessarily kill an entire query, it depends on the structure of your object graph. When a field request is terminated any down-stream child fields are discarded immediately but sibling fields or unrelated ancestors continue to execute as normal.
 
-Since this authorization occurs "per field" and not "per controller action" its possible to define the same security chain for POCO properties. This allows you to effectively deny access, by policy, to a single property of a single instantiated object if you wish. Performing security checks for every field of data (especially in parent/child scenarios) has a performance cost though, especially for larger data sets. For most scenarios enforcing security at the controller level is sufficient.
+Since this authorization occurs "per field" and not "per controller action" its possible to define the same security chain for POCO properties. This allows you to effectively deny access, by policy, to a single property of an instantiated object. Performing security checks for every field of data (especially in parent/child scenarios) has a performance cost though, especially for larger data sets. For most scenarios enforcing security at the controller level is sufficient.
 
 ## Authorization Failures are Obfuscated
 

docs/controllers/batch-operations.md

@@ -8,7 +8,7 @@ sidebar_label: Batch Operations
 
 ## The N+1 Problem
 
-There are plenty of articles on the web discussing the theory behind the N+1 problem (links below) Instead, we'll jump into an into an example to illustrate the issue when it comes to GraphQL.
+There are plenty of articles on the web discussing the theory behind the N+1 problem ([links below](./batch-operations#other-resources)). Instead, we'll jump into an into an example to illustrate the issue when it comes to GraphQL.
 
 Let's build on our example from the discussion on type extensions where we created an extension to retrieve `Cake Orders` for a **single** `Bakery`. What if we're a national chain and need to see the last 50 orders for each of our stores in a region? This seems like a reasonable thing an auditor would do so lets alter our controller to fetch all our bakeries and then let our type extension fetch the cake orders.
 
@@ -51,11 +51,11 @@ Well that was easy, right? Not so fast. The `bakeries` field returns a `List<Bak
 
 This is the N+1 problem. `1 query` for the bakeries + `N queries` for the cake orders, where N is the number of bakeries first retrieved.
 
-If we could _batch_ the cake orders request and fetch all the orders for all the bakeries at once, then assign the `Cake Orders` back to their bakeries, we'd be a lot better off. No matter the number of bakeries retrieved, we'd execute 2 queries; 1 for `bakeries` and 1 for `orders`.
+If we could _batch_ the cake orders request and fetch all the orders for all the bakeries at once, then assign the `Cake Orders` back to their respective bakeries, we'd be a lot better off. No matter the number of bakeries retrieved, we'd execute 2 queries; 1 for `bakeries` and 1 for `orders`.
 
 ## Data Loaders
 
-You'll often hear the term `Data Loaders` when reading about GraphQL implementations. Methods that load the child data being requested as a single operation before assigning to each of the parents. There is no difference with GraphQL ASP.NET. You still have to write that method. But with the ability to capture action method parameters and clever use of an `IGraphActionResult` we can combine the data load phase with the assignment phase into a single `batch operation`, at least on the surface. The aim is to make it easy to read and easier to write.
+You'll often hear the term `Data Loaders` when reading about GraphQL implementations. Methods that load the child data being requested as a single operation before assigning to each of the parents. There is no difference with GraphQL ASP.NET. You still have to write that method. But with the ability to capture action method parameters and clever use of an `IGraphActionResult` we can combine the data load phase with the assignment phase into a single batch operation, at least on the surface. The aim is to make it easy to read and easier to write.
 
 ## The [BatchTypeExtension] Attribute
 

docs/controllers/field-paths.md

@@ -1,10 +1,10 @@
 ---
 id: field-paths
-title: Field Paths
-sidebar_label: Field Paths
+title: Virtual Graph Types
+sidebar_label: Virtual Graph Types
 ---
 
-## What is Field Pathing?
+## What is a Virtual Graph Type?
 
 When we reason about ASP.NET MVC, routing comes naturally. We define a URL and perform an HTTP request to fetch data.
 
@@ -223,11 +223,11 @@ public class BakeryController : GraphController
 }
 ```
 
-Since both methods map to a field path of `[mutation]/bakery/orderDonuts` this would cause a `GraphTypeDeclarationException` to be thrown when your application starts.
+From a GraphQL perspective this equivilant to trying to define a `bakery` type with two fields named `orderDonuts`. Since both methods map to a field path of `[mutation]/bakery/orderDonuts` this would cause a `GraphTypeDeclarationException` to be thrown when your application starts. 
 
 With MVC the ASP.NET runtime could inspect any combinations of parameters passed on the query string or the POST body to work out which overload to call. You might be thinking, why can't GraphQL inspect the passed input arguments and make the same determination?
 
-In some cases it probably could. But looking at this example we run into an issue:
+Putting aside that it [violates the specification](http://spec.graphql.org/October2021/#sec-Objects), in some cases it probably could. But looking at this example we run into an issue:
 
 ```csharp
 // C# Controller

docs/controllers/type-extensions.md

@@ -68,7 +68,7 @@ Well that's just plain awful. We've over complicated our bakery model and made i
 
 ## The [TypeExtension] Attribute
 
-So what do we do? We've talked in the section on [field paths](./field-paths) about GraphQL maintaining a 1:1 mapping between a field in the graph and a method to retrieve data for it. What prevents us from creating a method to fetch a list of Cake Orders and saying, "Hey, GraphQL! When someone asks for the field `[type]/bakery/orders` call our method instead of a property getter on the `Bakery` class. As it turns out, that is exactly what a `Type Extension` does.
+So what do we do? We've talked in the section on [field paths](./field-paths) about GraphQL maintaining a 1:1 mapping between a field in the graph and a method to retrieve data for it (i.e. its assigned resolver). What prevents us from creating a method to fetch a list of Cake Orders and saying, "Hey, GraphQL! When someone asks for the field `[type]/bakery/orders` call our method instead of a property getter on the `Bakery` class. As it turns out, that is exactly what a `Type Extension` does.
 
 ```csharp
 // Bakery.cs
@@ -101,7 +101,7 @@ There is a lot to unpack here, so lets step through it:
 -   The method returns `List<CakeOrder>` as the type of data it generates.
 -   The method takes in a `Bakery` instance (more on that in a second) as well as an integer, with a default value of `15`, to limit the number of orders to retrieve.
 
-Now we can query the `orders` field from anywhere a bakery is returned in the object graph and GraphQL will invoke our method instead searching for a property named`Bakery.Orders`.
+Now we can query the `orders` field from anywhere a bakery is returned in the object graph and GraphQL will invoke our method instead searching for a property named `Bakery.Orders`.
 
 ```javascript
 query {
@@ -119,7 +119,7 @@ query {
 
 #### But what about the Bakery parameter?
 
-When you declare a `type extension` it will only be invoked in context of the type being extended.
+When you declare a type extension it will only be invoked in context of the type being extended.
 
 When we return a field of data from a property, an instance of the object must to exist in order to retrieve the property value. The same is true for a `type extension` except that instead of calling a property getter on the instance we're handing the entire instance to our method and letting it figure out what it needs to do with the data to resolve the field.
 

docs/reference/attributes.md

@@ -148,7 +148,7 @@ method should be invoked for a particular location.
     public sealed class AllowFragment : GraphDirective
     {
         [DirectiveLocations(ExecutableDirectiveLocation.FRAGMENT_SPREAD | ExecutableDirectiveLocation.INLINE_FRAGMENT)]
-        public IGraphActionResult BeforeFieldResolution([FromGraphQL("if")] bool ifArgument)
+        public IGraphActionResult Execute([FromGraphQL("if")] bool ifArgument)
         {
             return ifArgument ? this.Ok() : this.Cancel();
         }
@@ -169,7 +169,7 @@ during `SchemaGeneration` and `AfterFieldResolution` depending on the allowed ta
     public sealed class AllowFragment : GraphDirective
     {
         [DirectiveLocations(ExecutableDirectiveLocation.FIELD)]
-        public IGraphActionResult BeforeFieldResolution([FromGraphQL("if")] bool ifArgument)
+        public IGraphActionResult Execute([FromGraphQL("if")] bool ifArgument)
         {
             return ifArgument ? this.Ok() : this.Cancel();
         }

docs/types/input-objects.md

@@ -41,7 +41,7 @@ public class Donut
 
 ```
 // GraphQL Type Definition
-type NewDonutModel {
+input NewDonutModel {
   id: Int!
   name: String
   type: DonutType!
@@ -116,12 +116,9 @@ type Input_Donut {
 </div>
 <br/>
 
-
-> *Note:* `KeyValuePair<T, K>` is a commonly used struct. While it can be safely used as an `OBJECT` type, it should not be used as an `INPUT_OBJECT`. This is because, [by definition](https://github.com/dotnet/runtime/blob/main/src/libraries/System.Private.CoreLib/src/System/Collections/Generic/KeyValuePair.cs), `KeyValuePair<T,K>` does not declare publicly accessible setters on the `Key` and `Value` properties. Attempting to use the struct as an `INPUT_OBJECT` will not fail, but it will also not include any fields making it mostly useless.
-
 ## Methods are Ignored
 
-While its possible to have methods be exposed as fields on regular `OBJECT` types they are ignored for input arguments regardless of the declaration rules applied to the type.
+While its possible to have methods be exposed as fields on regular `OBJECT` types they are ignored for input types regardless of the declaration rules applied to the type.
 
 <div class="sideBySideCode hljs">
 <div>
@@ -146,9 +143,10 @@ public class Donut
 </div>
 <div>
 
-```
-// GraphQL Type Definition
-type Input_Donut {
+```ruby
+# GraphQL Type
+# Definition
+input Input_Donut {
   id: Int!
   name: String
   type: DonutType!
@@ -162,7 +160,7 @@ type Input_Donut {
 
 ## Working With Lists
 
-When constructing a set of items as an input value, GraphQL will instantiate a `List<T>` and fill it with the appropriate data, be that another list, another input object or a scalar. While you can declare a regular array (e.g. `Donut[]`, `int[]` etc.) as your list structure for an input argument, graphql has to rebuild its internal list structure as an array (or nested arrays) to meet the requirements of your method. In some cases, especially with nested lists, this result in an `O(n)` increase in processing time. It is recommended to use `IEnumerable<T>` or `IList<T>` to avoid this performance bottleneck when sending a lot of items as input arguments.
+When constructing a set of items as an input value, GraphQL will instantiate a `List<T>` and fill it with the appropriate data, be that another list, another input object or a scalar. While you can declare a regular array (e.g. `Donut[]`, `int[]` etc.) as your list structure for an input argument, graphql has to rebuild its internal list structure as an array (or nested arrays) to meet the requirements of your method. In some cases, especially with nested lists, this results in a linear increase in processing time. It is recommended to use `IEnumerable<T>` or `IList<T>` to avoid this performance bottleneck when sending a lot of items as input arguments.
 
 This example shows various ways of accepting collections of data as inputs to controller actions.
 

docs/types/interfaces.md

@@ -54,7 +54,7 @@ Most of the time GraphQL is smart enough to figure out which object types you're
 
 ## Use It To Include It
 
-When GraphQL ASP.NET starts building a schema it will read the interfaces attached to any model classes it finds and stage them in a special holding area. However, unless an interface is actually referenced as a return value of a field, be it from an action method or a model property, it won't be added to your schema and won't be visible to introspection queries. That is to say that when you register `Donut`, unless you specifically return `IPastry` from your application, GraphQL will leave it out of the schema. This goes a long ways in preventing clutter in your schema with all the interfaces you may declare internally.
+When GraphQL starts building a schema it will read the interfaces attached to any model classes it finds and stage them in a special holding area. However, unless an interface is actually referenced as a return value of a field, be it from an action method or a model property, it won't be added to your schema and won't be visible to introspection queries. That is to say that when you register `Donut`, unless you specifically return `IPastry` from your application, GraphQL will leave it out of the schema. This goes a long ways in preventing clutter in your schema with all the interfaces you may declare internally.
 
 <div class="sideBySideCode hljs">
 <div>
@@ -92,6 +92,7 @@ type Donut {
 </div>
 </div>
 
+<br/>
 Of course if you call `.AddGraphType<IPastry>()` during [schema configuration](../reference/schema-configuration) GraphQL will happily publish the type even if its never used in the graph.
 
 ## Interfaces are not Input Objects

docs/types/objects.md

@@ -6,7 +6,7 @@ sidebar_label: Objects
 
 The `object graph type` is one of six fundamental types defined by GraphQL. We can think of a graph query like a tree and if [scalar values](./scalars), such as `string` and `int`, are the leafs then objects are the branches.
 
-In GraphQL ASP.NET a C# `class` is used to identify an `object` in a schema.
+In GraphQL ASP.NET a C# `class` or `struct` is used to identify an `OBJECT` type in a schema.
 
 Here we've defined a `donut` model class. The runtime will convert it, automatically, into a graph type. If you're familiar with GraphQL's own type definition language the equivalent expression is shown to the right.
 
@@ -40,6 +40,7 @@ type Donut {
 </div>
 </div>
 
+<br/>
 \*The `DonutType` enumeration is covered in the [enum type](./enums) section.
 
 By Default, object graph types:
@@ -211,8 +212,8 @@ GraphQL will follow a cascading model of inclusion rules. Indicating a rule on t
 
 By Default, GraphQL won't include your class in a schema unless:
 
--   Its referenced in a controller.
--   Referenced by a graph type that is referenced in a controller.
+-   Its referenced in a controller OR
+-   Referenced by a graph type that is referenced in a controller OR
 -   Tagged with `[GraphType]`.
 
 But schema configurations can override this behavior and allow GraphQL to greedily include classes that it'll never use. This can expose them in an introspection query unintentionally. You can flag a class such that auto-inclusion will be skipped unless GraphQL can determine that the object is required to fulfill a request to the schema.
@@ -257,4 +258,4 @@ The usage of `struct` types as an `OBJECT` graph type is fully supported. The sa
 
 ## Reuse as Input Objects
 
-Both `class` and `struct` types can be used as an `INPUT_OBJECT` and an output `OBJECT` graph type. See the section on [input objects](./input-objects) for some of the key differences and requirements.
+Both `class` and `struct` types can be used as an `INPUT_OBJECT` and an `OBJECT` graph type. See the section on [input objects](./input-objects) for some of the key differences and requirements.

docs/types/unions.md

@@ -121,7 +121,7 @@ public class SaladOrBread : GraphUnionProxy
 
 ## Union Name Uniqueness
 
-Union names must be unique in a schema. If you do declare a union in multiple action methods without a proxy, GraphQL will attempt to validate the references by name and included types. As long as all declarations are the same, that is the name and the set of included types, then there graphql will accept the union. Otherwise, a `GraphTypeDeclarationException` will be thrown at startup.
+Union names must be unique in a schema. If you do declare a union in multiple action methods without a proxy, GraphQL will attempt to validate the references by name and included types. As long as all declarations are the same, that is the name and the set of included types, then graphql will accept the union. Otherwise, a `GraphTypeDeclarationException` will be thrown at startup.
 
 ## Liskov Substitutions
 
@@ -225,7 +225,7 @@ public class BakeryController : GraphController
 ```
 
 > Note: `MapType` is not based on the resolved field value, but only on the `System.Type`. This is by design to guarantee consistency in query execution. 
-> If your returned type causes the query to remain indeterminate a validation error (rule 6.4.3) will be applied to the query.
+> If your returned type causes the query to remain indeterminate a validation error (rule [6.4.3](https://spec.graphql.org/October2021/#sec-Value-Completion)) will be applied to the query.
 
 The query will now interpret all `Bagels` as `Rolls` and be able to process the query correctly.