Document use of DataFetcherResult for injecting values in local context

[bclozel]

See #1142 for background

Right now Annotated controllers support many method arguments, including:

• @ContextValue, for access to an attribute from the main GraphQLContext in DataFetchingEnvironment.
• @LocalContextValue, for access to an attribute from the local GraphQLContext in DataFetchingEnvironment.
• GraphQLContext, for access to the context from the DataFetchingEnvironment.

Controller methods can only contribute a new local context by returning a DataFetcherResult<ReturnType>. Spring MVC does support java.util.Map, org.springframework.ui.Model, org.springframework.ui.ModelMap as mutable maps to be used when rendering a view. Injecting a new, mutable GraphQLContext local context would be quite similar to existing MVC support but might be confusing given the extensive context support we already have.

As part of this issue, we should first document the DataFetcherResult route and then consider whether we want to improve support.

[bclozel]

Here's a first version of our documentation section.

[bclozel]

We discussed the possibility of adding specific support for Local Contexts in the controller method signatures, but we decided against it in the end for the following reasons:

• the DataFetcherResult API is quite sensible already
• so far, we only inject input values as method parameters and injecting somehow a new local context instance would break this rule
• usage of local context is not central to GraphQL applications, unlike Model for MVC apps. Even there, we also often use ModelAndView or Rendering return types
• this support would require more than a typical argument resolved, as we would need to also wrap the response with a DataFetcherResult
• we would have to specify the behavior when the method gets injected with a local context and also returns a DataFetcherResult
• We can't simply rely on the GraphQLContext type for method argument resolution as it's already used for the main context. We would need maybe to contribute a new specific type

Overall, we don't think working on a new feature there is worth it right now.