chore: various minor fixes, PR self review

Author: maurei

src/Examples/JsonApiDotNetCoreExample/Controllers/Restricted/ReadOnlyController.cs

@@ -3,7 +3,6 @@
 
 namespace JsonApiDotNetCoreExample.Controllers.Restricted
 {
-
     [Route("[controller]")]
     [HttpReadOnly]
     public class ReadOnlyController : ControllerBase

src/Examples/JsonApiDotNetCoreExample/Services/CustomArticleService.cs

@@ -16,7 +16,19 @@ namespace JsonApiDotNetCoreExample.Services
 {
     public class CustomArticleService : EntityResourceService<Article>
     {
-        public CustomArticleService(ISortService sortService, IFilterService filterService, IEntityRepository<Article, int> repository, IJsonApiOptions options, ICurrentRequest currentRequest, IIncludeService includeService, ISparseFieldsService sparseFieldsService, IPageService pageManager, IResourceGraph resourceGraph, IResourceHookExecutor hookExecutor = null, ILoggerFactory loggerFactory = null) : base(sortService, filterService, repository, options, currentRequest, includeService, sparseFieldsService, pageManager, resourceGraph, hookExecutor, loggerFactory)
+        public CustomArticleService(ISortService sortService,
+                                    IFilterService filterService,
+                                    IEntityRepository<Article, int> repository,
+                                    IJsonApiOptions options,
+                                    ICurrentRequest currentRequest,
+                                    IIncludeService includeService,
+                                    ISparseFieldsService sparseFieldsService,
+                                    IPageService pageManager,
+                                    IResourceGraph resourceGraph,
+                                    IResourceHookExecutor hookExecutor = null,
+                                    ILoggerFactory loggerFactory = null)
+            : base(sortService, filterService, repository, options, currentRequest, includeService, sparseFieldsService,
+                   pageManager, resourceGraph, hookExecutor, loggerFactory)
         {
         }
 

src/Examples/NoEntityFrameworkExample/Properties/launchSettings.json

@@ -8,20 +8,20 @@
     }
   },
   "profiles": {
-    "IIS Express": {
-      "commandName": "IISExpress",
-      "launchBrowser": true,
-      "environmentVariables": {
-        "ASPNETCORE_ENVIRONMENT": "Development"
-      }
-    },
     "NoEntityFrameworkExample": {
       "commandName": "Project",
       "launchBrowser": true,
       "environmentVariables": {
         "ASPNETCORE_ENVIRONMENT": "Development"
       },
       "applicationUrl": "http://localhost:5000/"
+    },
+    "IIS Express": {
+      "commandName": "IISExpress",
+      "launchBrowser": true,
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
     }
   }
 }

src/JsonApiDotNetCore/Controllers/DisableQueryAttribute.cs

@@ -3,12 +3,22 @@
 namespace JsonApiDotNetCore.Controllers
 {
     public class DisableQueryAttribute : Attribute
-    { 
+    {
+        /// <summary>
+        /// Disabled one of the native query parameters for a controller.
+        /// </summary>
+        /// <param name="queryParams"></param>
         public DisableQueryAttribute(QueryParams queryParams)
         {
             QueryParams = queryParams.ToString("G").ToLower();
         }
 
+        /// <summary>
+        /// It is allowed to use strings to indicate which query parameters
+        /// should be disabled, because the user may have defined a custom
+        /// query parameter that is not included in the  <see cref="QueryParams"/> enum.
+        /// </summary>
+        /// <param name="customQueryParams"></param>
         public DisableQueryAttribute(string customQueryParams)
         {
             QueryParams = customQueryParams.ToLower();

src/JsonApiDotNetCore/Internal/Query/QueryConstants.cs

@@ -1,17 +1,11 @@
 namespace JsonApiDotNetCore.Internal.Query
 {
     public static class QueryConstants {
-        public const string FILTER = "filter";
-        public const string SORT = "sort";
-        public const string INCLUDE = "include";
-        public const string PAGE = "page";
-        public const string FIELDS = "fields";
         public const char OPEN_BRACKET = '[';
         public const char CLOSE_BRACKET = ']';
         public const char COMMA = ',';
         public const char COLON = ':';
         public const string COLON_STR = ":";
         public const char DOT = '.';
-
     }
 }

src/JsonApiDotNetCore/JsonApiDotNetCore.csproj

@@ -44,17 +44,4 @@
   <ItemGroup Condition="'$(GenerateDocumentation)' == 'true'">
     <PackageReference Include="docfx.console" Version="2.33.0" />
   </ItemGroup>
-  <ItemGroup>
-    <Folder Include="Models\JsonApiDocuments\" />
-    <Folder Include="QueryParameterServices\" />
-    <Folder Include="Internal\Exceptions\" />
-    <Folder Include="Models\Annotation\" />
-    <Folder Include="Serialization\Common\" />
-    <Folder Include="Serialization\Client\" />
-    <Folder Include="Serialization\Server\" />
-    <Folder Include="Serialization\Server\Builders\" />
-    <Folder Include="QueryParameterServices\Contracts\" />
-    <Folder Include="QueryParameterServices\Common\" />
-    <Folder Include="Serialization\Server\Contracts\" />
-  </ItemGroup>
 </Project>

src/JsonApiDotNetCore/QueryParameterServices/Common/IQueryParameterParser.cs

@@ -7,7 +7,7 @@ namespace JsonApiDotNetCore.Services
     /// Responsible for populating the various service implementations of
     /// <see cref="IQueryParameterService"/>.
     /// </summary>
-    public interface IQueryParameterParser
+    public interface IQueryParameterDiscovery
     {
         void Parse(IQueryCollection query, DisableQueryAttribute disabledQuery = null);
     }

src/JsonApiDotNetCore/QueryParameterServices/Common/IQueryParameterService.cs

@@ -11,7 +11,7 @@ public interface IQueryParameterService
         /// <summary>
         /// Parses the value of the query parameter. Invoked in the middleware.
         /// </summary>
-        /// <param name="queryParameter">the value of the query parameter as parsed from the url</param>
+        /// <param name="queryParameter">the value of the query parameter as retrieved from the url</param>
         void Parse(KeyValuePair<string, StringValues> queryParameter);
         /// <summary>
         /// The name of the query parameter as matched in the URL query string.

src/JsonApiDotNetCore/QueryParameterServices/Common/QueryParameterService.cs

@@ -64,7 +64,6 @@ protected AttrAttribute GetAttribute(string target, RelationshipAttribute relati
             return attribute;
         }
 
-
         /// <summary>
         /// Helper method for parsing query parameters into relationships attributes
         /// </summary>

src/JsonApiDotNetCore/QueryParameterServices/Contracts/IFilterService.cs

@@ -3,8 +3,14 @@
 
 namespace JsonApiDotNetCore.Query
 {
+    /// <summary>
+    /// Query parameter service responsible for url queries of the form ?filter[X]=Y
+    /// </summary>
     public interface IFilterService : IQueryParameterService
     {
+        /// <summary>
+        /// Gets the parsed filter queries
+        /// </summary>
         List<FilterQueryContext> Get();
     }
 }

src/JsonApiDotNetCore/QueryParameterServices/Contracts/IIncludeService.cs

@@ -4,12 +4,12 @@
 namespace JsonApiDotNetCore.Query
 {
     /// <summary>
-    /// Query service to access the inclusion chains.
+    /// Query parameter service responsible for url queries of the form ?include=X.Y.Z,U.V.W
     /// </summary>
     public interface IIncludeService : IQueryParameterService
     {
         /// <summary>
-        /// Gets the list of included relationships chains for the current request.
+        /// Gets the parsed relationship inclusion chains.
         /// </summary>
         List<List<RelationshipAttribute>> Get();
     }

src/JsonApiDotNetCore/QueryParameterServices/Contracts/IOmitDefaultService.cs

@@ -1,7 +1,13 @@
 namespace JsonApiDotNetCore.Query
 {
+    /// <summary>
+    /// Query parameter service responsible for url queries of the form ?omitDefault=true
+    /// </summary>
     public interface IOmitDefaultService : IQueryParameterService
     {
+        /// <summary>
+        /// Gets the parsed config
+        /// </summary>
         bool Config { get; }
     }
 }

src/JsonApiDotNetCore/QueryParameterServices/Contracts/IOmitNullService.cs

@@ -1,7 +1,13 @@
 namespace JsonApiDotNetCore.Query
 {
+    /// <summary>
+    /// Query parameter service responsible for url queries of the form ?omitNull=true
+    /// </summary>
     public interface IOmitNullService : IQueryParameterService
     {
+        /// <summary>
+        /// Gets the parsed config
+        /// </summary>
         bool Config { get; }
     }
 }

src/JsonApiDotNetCore/QueryParameterServices/Contracts/IPageService.cs

@@ -1,7 +1,7 @@
 namespace JsonApiDotNetCore.Query
 {
     /// <summary>
-    /// The former page manager. Needs some work.
+    /// Query parameter service responsible for url queries of the form ?page[size]=X&page[number]=Y
     /// </summary>
     public interface IPageService : IQueryParameterService
     {
@@ -28,7 +28,7 @@ public interface IPageService : IQueryParameterService
         int TotalPages { get; }
 
         /// <summary>
-        /// Pagination is enabled
+        /// Checks if pagination is enabled
         /// </summary>
         bool ShouldPaginate();
     }

src/JsonApiDotNetCore/QueryParameterServices/Contracts/ISortService.cs

@@ -3,8 +3,14 @@
 
 namespace JsonApiDotNetCore.Query
 {
+    /// <summary>
+    /// Query parameter service responsible for url queries of the form ?sort=-X
+    /// </summary>
     public interface ISortService : IQueryParameterService
     {
+        /// <summary>
+        /// Gets the parsed sort queries
+        /// </summary>
         List<SortQueryContext> Get();
     }
 }

src/JsonApiDotNetCore/QueryParameterServices/Contracts/ISparseFieldsService.cs

@@ -4,12 +4,12 @@
 namespace JsonApiDotNetCore.Query
 {
     /// <summary>
-    /// Query service to access sparse field selection.
+    /// Query parameter service responsible for url queries of the form ?fields[X]=U,V,W
     /// </summary>
     public interface ISparseFieldsService : IQueryParameterService
     {
         /// <summary>
-        /// Gets the list of targeted fields. In a relationship is supplied,
+        /// Gets the list of targeted fields. If a relationship is supplied,
         /// gets the list of targeted fields for that relationship.
         /// </summary>
         /// <param name="relationship"></param>

src/JsonApiDotNetCore/QueryParameterServices/FilterService.cs

@@ -10,9 +10,9 @@
 
 namespace JsonApiDotNetCore.Query
 {
+    /// <inheritdoc/>
     public class FilterService : QueryParameterService, IFilterService
     {
-
         private readonly List<FilterQueryContext> _filters;
         private IResourceDefinition _requestResourceDefinition;
 
@@ -22,11 +22,13 @@ public FilterService(IResourceDefinitionProvider resourceDefinitionProvider, ICo
             _filters = new List<FilterQueryContext>();
         }
 
+        /// <inheritdoc/>
         public List<FilterQueryContext> Get()
         {
             return _filters;
         }
 
+        /// <inheritdoc/>
         public virtual void Parse(KeyValuePair<string, StringValues> queryParameter)
         {
             var queries = GetFilterQueries(queryParameter);

src/JsonApiDotNetCore/QueryParameterServices/IncludeService.cs

@@ -9,7 +9,6 @@
 
 namespace JsonApiDotNetCore.Query
 {
-
     public class IncludeService : QueryParameterService, IIncludeService
     {
         /// todo: use read-only lists.

src/JsonApiDotNetCore/QueryParameterServices/OmitDefaultService.cs

@@ -4,6 +4,7 @@
 
 namespace JsonApiDotNetCore.Query
 {
+    /// <inheritdoc/>
     public class OmitDefaultService : QueryParameterService, IOmitDefaultService
     {
         private readonly IJsonApiOptions _options;
@@ -14,8 +15,10 @@ public OmitDefaultService(IJsonApiOptions options)
             _options = options;
         }
 
+        /// <inheritdoc/>
         public bool Config { get; private set; }
 
+        /// <inheritdoc/>
         public virtual void Parse(KeyValuePair<string, StringValues> queryParameter)
         {
             if (!_options.DefaultAttributeResponseBehavior.AllowClientOverride)

src/JsonApiDotNetCore/QueryParameterServices/OmitNullService.cs

@@ -1,11 +1,10 @@
-using System;
 using System.Collections.Generic;
 using JsonApiDotNetCore.Configuration;
-using JsonApiDotNetCore.Internal;
 using Microsoft.Extensions.Primitives;
 
 namespace JsonApiDotNetCore.Query
 {
+    /// <inheritdoc/>
     public class OmitNullService : QueryParameterService, IOmitNullService
     {
         private readonly IJsonApiOptions _options;
@@ -16,8 +15,10 @@ public OmitNullService(IJsonApiOptions options)
             _options = options;
         }
 
+        /// <inheritdoc/>
         public bool Config { get; private set; }
 
+        /// <inheritdoc/>
         public virtual void Parse(KeyValuePair<string, StringValues> queryParameter)
         {
             if (!_options.NullAttributeResponseBehavior.AllowClientOverride)

src/JsonApiDotNetCore/QueryParameterServices/PageService.cs

@@ -7,6 +7,7 @@
 
 namespace JsonApiDotNetCore.Query
 {
+    /// <inheritdoc/>
     public class PageService : QueryParameterService, IPageService
     {
         private IJsonApiOptions _options;
@@ -28,7 +29,8 @@ public PageService(IJsonApiOptions options)
         /// <inheritdoc/>
         public int TotalPages => (TotalRecords == null) ? -1 : (int)Math.Ceiling(decimal.Divide(TotalRecords.Value, PageSize));
 
-        public override void Parse(KeyValuePair<string, StringValues> queryParameter)
+        /// <inheritdoc/>
+        public virtual void Parse(KeyValuePair<string, StringValues> queryParameter)
         {
             // expected input = page[size]=10
             //                  page[number]=1
@@ -53,7 +55,6 @@ public override void Parse(KeyValuePair<string, StringValues> queryParameter)
             }
         }
 
-
         /// <inheritdoc/>
         public bool ShouldPaginate()
         {

src/JsonApiDotNetCore/QueryParameterServices/SortService.cs

@@ -8,6 +8,7 @@
 
 namespace JsonApiDotNetCore.Query
 {
+    /// <inheritdoc/>
     public class SortService : QueryParameterService, ISortService
     {
         const char DESCENDING_SORT_OPERATOR = '-';