docs: comments JsonApiApplicationBuilder

Author: maurei

src/JsonApiDotNetCore/Builders/JsonApiApplicationBuilder.cs

@@ -23,6 +23,10 @@
 
 namespace JsonApiDotNetCore.Builders
 {
+ /// <summary>
+ /// A utility class that builds a JsonApi application. It registers all required services
+ /// and allows the user to override parts of the startup configuration.
+ /// </summary>
  public class JsonApiApplicationBuilder
  {
  public readonly JsonApiOptions JsonApiOptions = new JsonApiOptions();
@@ -38,8 +42,17 @@ public JsonApiApplicationBuilder(IServiceCollection services, IMvcCoreBuilder mv
  _mvcBuilder = mvcBuilder;
  }
 
+ /// <summary>
+ /// Executes the action provided by the user to configure <see cref="JsonApiOptions"/>
+ /// </summary>
  public void ConfigureJsonApiOptions(Action<JsonApiOptions> configureOptions) => configureOptions(JsonApiOptions);
 
+ /// <summary>
+ /// Configures built-in .net core MVC (things like middleware, routing). Most of this configuration can be adjusted for the developers need.
+ /// Before calling .AddJsonApi(), a developer can register their own implementation of the following services to customize startup:
+ /// <see cref="IResourceGraphBuilder"/>, <see cref="IServiceDiscoveryFacade"/>, <see cref="IJsonApiExceptionFilterProvider"/>,
+ /// <see cref="IJsonApiTypeMatchFilterProvider"/>, <see cref="IJsonApiRoutingConvention"/> and <see cref="IResourceNameFormatter"/>.
+ /// </summary>
  public void ConfigureMvc()
  {
  RegisterJsonApiStartupServices();
@@ -63,16 +76,27 @@ public void ConfigureMvc()
  _services.AddSingleton(routingConvention); // <--- why is this needed?
  }
 
+ /// <summary>
+ /// Executes autodiscovery of JADNC services.
+ /// </summary>
  public void AutoDiscover(Action<IServiceDiscoveryFacade> autoDiscover)
  {
  autoDiscover(_serviceDiscoveryFacade);
  }
 
+ /// <summary>
+ /// Executes the action provided by the user to configure the resources using <see cref="IResourceGraphBuilder"/>
+ /// </summary>
+ /// <param name="resourceGraphBuilder"></param>
  public void ConfigureResources(Action<IResourceGraphBuilder> resourceGraphBuilder)
  {
  resourceGraphBuilder(_resourceGraphBuilder);
  }
 
+ /// <summary>
+ /// Executes the action provided by the user to configure the resources using <see cref="IResourceGraphBuilder"/>.
+ /// Additionally, inspects the EF core database context for models that implement IIdentifiable.
+ /// </summary>
  public void ConfigureResources<TContext>(Action<IResourceGraphBuilder> resourceGraphBuilder) where TContext : DbContext
  {
  _resourceGraphBuilder.AddDbContext<TContext>();
@@ -81,17 +105,9 @@ public void ConfigureResources<TContext>(Action<IResourceGraphBuilder> resourceG
  resourceGraphBuilder?.Invoke(_resourceGraphBuilder);
  }
 
- private void RegisterJsonApiStartupServices()
- {
- _services.AddSingleton<IJsonApiOptions>(JsonApiOptions);
- _services.TryAddSingleton<IResourceNameFormatter>(new KebabCaseFormatter());
- _services.TryAddSingleton<IJsonApiRoutingConvention, DefaultRoutingConvention>();
- _services.TryAddSingleton<IResourceGraphBuilder, ResourceGraphBuilder>();
- _services.TryAddSingleton<IServiceDiscoveryFacade>(sp => new ServiceDiscoveryFacade(_services, sp.GetRequiredService<IResourceGraphBuilder>()));
- _services.TryAddScoped<IJsonApiExceptionFilterProvider, JsonApiExceptionFilterProvider>();
- _services.TryAddScoped<IJsonApiTypeMatchFilterProvider, JsonApiTypeMatchFilterProvider>();
- }
-
+ /// <summary>
+ /// Registers the remaining internals.
+ /// </summary>
  public void ConfigureServices()
  {
  var resourceGraph = _resourceGraphBuilder.Build();
@@ -154,7 +170,6 @@ public void ConfigureServices()
  _services.AddScoped<IInverseRelationships, InverseRelationships>();
  }
 
-
  private void AddQueryParameterServices()
  {
  _services.AddScoped<IIncludeService, IncludeService>();
@@ -174,7 +189,6 @@ private void AddQueryParameterServices()
  _services.AddScoped<IQueryParameterService>(sp => sp.GetService<IOmitNullService>());
  }
 
-
  private void AddResourceHooks()
  {
  _services.AddSingleton(typeof(IHooksDiscovery<>), typeof(HooksDiscovery<>));
@@ -196,5 +210,16 @@ private void AddServerSerialization()
  _services.AddScoped(sp => sp.GetRequiredService<IJsonApiSerializerFactory>().GetSerializer());
  _services.AddScoped<IResourceObjectBuilder, ResponseResourceObjectBuilder>();
  }
+
+ private void RegisterJsonApiStartupServices()
+ {
+ _services.AddSingleton<IJsonApiOptions>(JsonApiOptions);
+ _services.TryAddSingleton<IResourceNameFormatter>(new KebabCaseFormatter());
+ _services.TryAddSingleton<IJsonApiRoutingConvention, DefaultRoutingConvention>();
+ _services.TryAddSingleton<IResourceGraphBuilder, ResourceGraphBuilder>();
+ _services.TryAddSingleton<IServiceDiscoveryFacade>(sp => new ServiceDiscoveryFacade(_services, sp.GetRequiredService<IResourceGraphBuilder>()));
+ _services.TryAddScoped<IJsonApiExceptionFilterProvider, JsonApiExceptionFilterProvider>();
+ _services.TryAddScoped<IJsonApiTypeMatchFilterProvider, JsonApiTypeMatchFilterProvider>();
+ }
  }
 }

src/JsonApiDotNetCore/Middleware/IJsonApiTypeMatchFilterProvider.cs

@@ -4,7 +4,7 @@ namespace JsonApiDotNetCore.Middleware
 {
  /// <summary>
  /// Provides the type of the global action filter that is configured in MVC during startup.
- /// This can be overridden to let JADNC use your own exception filter. The default exception filter used
+ /// This can be overridden to let JADNC use your own action filter. The default action filter used
  /// is <see cref="DefaultTypeMatchFilter"/>
  /// </summary>
  public interface IJsonApiTypeMatchFilterProvider