Refactoring in reference docs

Consolidate the content on `@SchemaMapping` into its own sub-section
and make it consistent with the same for `@BatchMapping`.

See gh-130

Author: rstoyanchev

spring-graphql-docs/src/docs/asciidoc/index.adoc

@@ -314,7 +314,7 @@ Spring GraphQL exposes a `BatchLoaderRegistry` that accepts and stores registrat
 batch loading functions. The `ExecutionGraphQlService` accepts the registry as input and
 uses it to make per request `DataLoader` registrations. A `DataFetcher` then looks up the
 `DataLoader` for an entity and uses it to load instances, or in an annotated controller,
-simply declare a <<controllers-data-loader,DataLoader argument>> to access  the
+simply declare a <<controllers-schema-mapping-data-loader,DataLoader argument>> to access  the
 registered loader. Annotated controllers also support a
 <<controllers-batch-mapping,@BatchMapping>> that avoids the need to use `DataLoader`
 directly.
@@ -447,8 +447,8 @@ and adds all `RuntimeWiringConfigurer` beans to `GraphQlSource.Builder` and that
 support for annotated ``DataFetcher``s, see <<boot-graphql-runtimewiring>>.
 
 
-[[controllers-mapping]]
-=== Mapping
+[[controllers-schema-mapping]]
+=== `@SchemaMapping`
 
 The `@SchemaMapping` annotation maps a handler method to a field in the GraphQL schema
 and declares it to be the `DataFetcher` for that field. The annotation can specify the
@@ -524,148 +524,47 @@ for fields under the Query, Mutation, and Subscription types respectively. For e
 	}
 ----
 
-
-[[controllers-batch-mapping]]
-=== Batch Mapping
-
-<<execution-batching>> addresses the N+1 select problem through the use of an
-`org.dataloader.DataLoader` to defer the loading of individual entity instances, so they
-can be loaded together. For example:
-
-[source,java,indent=0,subs="verbatim,quotes"]
-----
-@Controller
-public class BookController {
-
-	public BookController(BatchLoaderRegistry registry) {
-		registry.forTypePair(Long.class, Author.class).registerMappedBatchLoader((authorIds, env) -> {
-			// return Map<Long, Author>
-		});
-	}
-
-	@SchemaMapping
-	public CompletableFuture<Author> author(Book book, DataLoader<Long, Author> loader) {
-		return loader.load(book.getAuthorId());
-	}
-
-}
-----
-
-For the straight-forward case of loading an associated entity, shown above, the
-`@SchemaMapping` method does nothing more than delegate to the `DataLoader`. This is
-boilerplate that can be avoided with a `@BatchMapping` method. For example:
-
-[source,java,indent=0,subs="verbatim,quotes"]
-----
-	@Controller
-	public class BookController {
-
-		@BatchMapping
-		public Mono<Map<Book, Author>> author(List<Book> books) {
-			// ...
-		}
-	}
-----
-
-The above becomes a batch loading function in the `BatchLoaderRegistry`
-where keys are `Book` instances and the loaded values their authors. In addition, a
-`DataFetcher` is also transparently bound to the `author` field of the type `Book`, which
-simply delegates to the `DataLoader` for authors, given its source/parent `Book` instance.
-
-[TIP]
-====
-To be used as a unique key, `Book` must implement `hashcode` and `equals`.
-====
-
-By default, the field name defaults to the method name, while the type name defaults to
-the simple class name of the input `List` element type. Both can be customized through
-annotation attributes. The type name can also be inherited from a class level
-`@SchemaMapping`.
-
-A `@BatchMapping` method can also return a sequence of instances, and that needs to match
-the order of the source/parent objects:
-
-[source,java,indent=0,subs="verbatim,quotes"]
-----
-	@Controller
-	public class BookController {
-
-		@BatchMapping
-		public Flux<Author> author(List<Book> books) {
-			// ...
-		}
-	}
-----
-
-It is possible to use imperative method signatures too, i.e. returning `Map<K, V>` or
-`List<V>`, which can be useful when there are no remote calls to make.
-
-`BatchMapping` methods support two types of arguments:
-
-[cols="1,2"]
-|===
-| Method Argument | Description
-
-| `List<K>`
-| The source/parent objects.
-
-| `BatchLoaderEnvironment`
-| The environment that is available in GraphQL Java to a
-  `org.dataloader.BatchLoaderWithContext`.
-
-|===
-
-
-
-
-[[controllers-methods]]
-=== Handler Methods
-
 `@SchemaMapping` handler methods have flexible signatures and can choose from a range of
 method arguments and return values..
 
 
-[[controllers-arguments]]
-==== Method Arguments
+[[controllers-schema-mapping-signature]]
+==== Method Signature
 
-Annotated handler methods can choose from one of the following method arguments:
+Schema mapping handler methods can have any of the following method arguments:
 
 [cols="1,2"]
 |===
 | Method Argument | Description
 
 | `@Argument`
 | For access to field arguments with conversion.
-  See <<controllers-argument>>.
+See <<controllers-schema-mapping-argument>>.
 
 | Source
 | For access to the source (i.e. parent/container) instance of the field.
-  See <<controllers-source>>.
+See <<controllers-schema-mapping-source>>.
 
 | `DataLoader`
 | For access to a `DataLoader` in the `DataLoaderRegistry`.
-See <<controllers-data-loader>>.
+See <<controllers-schema-mapping-data-loader>>.
 
 | `GraphQLContext`
 | For access to the context from the `DataFetchingEnvironment`.
-See <<controllers-graphql-context>>.
+See <<controllers-schema-mapping-graphql-context>>.
 
 | `DataFetchingEnvironment`
 | For direct access to the underlying `DataFetchingEnvironment`.
-See <<controllers-environment>>.
+See <<controllers-schema-mapping-environment>>.
 
 |===
 
+Schema mapping handler methods can return any value, including Reactor `Mono` and
+`Flux` as described in <<execution-reactive-datafetcher>>.
 
-[[controllers-return-values]]
-==== Return Values
-
-Annotated handler methods can return any value, including Reactor `Mono` and `Flux` as
-described in <<execution-reactive-datafetcher>>.
 
 
-
-[[controllers-argument]]
+[[controllers-schema-mapping-argument]]
 ==== `@Argument`
 
 In GraphQL Java, the `DataFetchingEnvironment` provides access to field-specific argument
@@ -704,7 +603,7 @@ You can use `@Argument` on a `Map<String, Object>` argument, to obtain all argum
 values. The name attribute on `@Argument` must not be set.
 
 
-[[controllers-source]]
+[[controllers-schema-mapping-source]]
 ==== Source
 
 In GraphQL Java, the `DataFetchingEnvironment` provides access to the source (i.e.
@@ -727,8 +626,15 @@ The source method argument also helps to determine the type name for the mapping
 If the simple name of the Java class matches the GraphQL type, then there is no need to
 explicitly specify the type name in the `@SchemaMapping` annotation.
 
+[TIP]
+====
+A <<controllers-batch-mapping>> handler method can batch load all authors for a query,
+given a list of source/parent books objects.
+====
+
+
 
-[[controllers-data-loader]]
+[[controllers-schema-mapping-data-loader]]
 ==== `DataLoader`
 
 When you register a batch loading function for an entity, as explained in
@@ -769,21 +675,117 @@ instead.
 ====
 
 
-[[controllers-graphql-context]]
+[[controllers-schema-mapping-graphql-context]]
 ==== `GraphQLContext`
 
 To access the `GraphQLContext` from the `DataFetchingEnvironment`, declare a method
 parameter of the same type.
 
 
-[[controllers-environment]]
+[[controllers-schema-mapping-environment]]
 ==== `DataFetchingEnvironment`
 
 To access the `DataFetchingEnvironment` directly, declare a method parameter of the same
 type.
 
 
 
+[[controllers-batch-mapping]]
+=== `@BatchMapping`
+
+<<execution-batching>> addresses the N+1 select problem through the use of an
+`org.dataloader.DataLoader` to defer the loading of individual entity instances, so they
+can be loaded together. For example:
+
+[source,java,indent=0,subs="verbatim,quotes"]
+----
+@Controller
+public class BookController {
+
+	public BookController(BatchLoaderRegistry registry) {
+		registry.forTypePair(Long.class, Author.class).registerMappedBatchLoader((authorIds, env) -> {
+			// return Map<Long, Author>
+		});
+	}
+
+	@SchemaMapping
+	public CompletableFuture<Author> author(Book book, DataLoader<Long, Author> loader) {
+		return loader.load(book.getAuthorId());
+	}
+
+}
+----
+
+For the straight-forward case of loading an associated entity, shown above, the
+`@SchemaMapping` method does nothing more than delegate to the `DataLoader`. This is
+boilerplate that can be avoided with a `@BatchMapping` method. For example:
+
+[source,java,indent=0,subs="verbatim,quotes"]
+----
+	@Controller
+	public class BookController {
+
+		@BatchMapping
+		public Mono<Map<Book, Author>> author(List<Book> books) {
+			// ...
+		}
+	}
+----
+
+The above becomes a batch loading function in the `BatchLoaderRegistry`
+where keys are `Book` instances and the loaded values their authors. In addition, a
+`DataFetcher` is also transparently bound to the `author` field of the type `Book`, which
+simply delegates to the `DataLoader` for authors, given its source/parent `Book` instance.
+
+[TIP]
+====
+To be used as a unique key, `Book` must implement `hashcode` and `equals`.
+====
+
+By default, the field name defaults to the method name, while the type name defaults to
+the simple class name of the input `List` element type. Both can be customized through
+annotation attributes. The type name can also be inherited from a class level
+`@SchemaMapping`.
+
+[[controllers-batch-mapping-signature]]
+==== Method Signature
+
+Batch mapping methods support two types of arguments:
+
+[cols="1,2"]
+|===
+| Method Argument | Description
+
+| `List<K>`
+| The source/parent objects.
+
+| `BatchLoaderEnvironment`
+| The environment that is available in GraphQL Java to a
+`org.dataloader.BatchLoaderWithContext`.
+
+|===
+
+Batch mapping methods can return:
+
+[cols="1,2"]
+|===
+| Return Type | Description
+
+| `Mono<Map<K,V>>`
+| A map with parent objects as keys, and batch loaded objects as values.
+
+| `Flux<V>`
+| A sequence of batch loaded objects that must be in the same order as the source/parent
+  objects passed into the method.
+
+| `Map<K,V>`, `Flux<V>`
+| Imperative variants, e.g. without remote calls to make.
+
+|===
+
+
+
+
 [[security]]
 == Security