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