chore: various minor fixes, PR self review

maurei · maurei · commit d1af7cc52035 · 2019-10-15T13:42:39.000+02:00
diff --git a/src/Examples/JsonApiDotNetCoreExample/Controllers/Restricted/ReadOnlyController.cs b/src/Examples/JsonApiDotNetCoreExample/Controllers/Restricted/ReadOnlyController.cs
@@ -3,7 +3,6 @@
 
 namespace JsonApiDotNetCoreExample.Controllers.Restricted
 {
-
     [Route("[controller]")]
     [HttpReadOnly]
     public class ReadOnlyController : ControllerBase
diff --git a/src/Examples/JsonApiDotNetCoreExample/Services/CustomArticleService.cs b/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)
         {
         }
 
diff --git a/src/Examples/NoEntityFrameworkExample/Properties/launchSettings.json b/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"
+      }
     }
   }
 }
diff --git a/src/JsonApiDotNetCore/Controllers/DisableQueryAttribute.cs b/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();
diff --git a/src/JsonApiDotNetCore/Internal/Query/QueryConstants.cs b/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 = '.';
-
     }
 }
diff --git a/src/JsonApiDotNetCore/JsonApiDotNetCore.csproj b/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>
diff --git a/src/JsonApiDotNetCore/QueryParameterServices/Common/IQueryParameterParser.cs b/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);
     }
diff --git a/src/JsonApiDotNetCore/QueryParameterServices/Common/IQueryParameterService.cs b/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.
diff --git a/src/JsonApiDotNetCore/QueryParameterServices/Common/QueryParameterService.cs b/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>
diff --git a/src/JsonApiDotNetCore/QueryParameterServices/Contracts/IFilterService.cs b/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();
     }
 }
diff --git a/src/JsonApiDotNetCore/QueryParameterServices/Contracts/IIncludeService.cs b/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();
     }
diff --git a/src/JsonApiDotNetCore/QueryParameterServices/Contracts/IOmitDefaultService.cs b/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; }
     }
 }
diff --git a/src/JsonApiDotNetCore/QueryParameterServices/Contracts/IOmitNullService.cs b/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; }
     }
 }
diff --git a/src/JsonApiDotNetCore/QueryParameterServices/Contracts/IPageService.cs b/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();
     }
diff --git a/src/JsonApiDotNetCore/QueryParameterServices/Contracts/ISortService.cs b/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();
     }
 }
diff --git a/src/JsonApiDotNetCore/QueryParameterServices/Contracts/ISparseFieldsService.cs b/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>
diff --git a/src/JsonApiDotNetCore/QueryParameterServices/FilterService.cs b/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);
diff --git a/src/JsonApiDotNetCore/QueryParameterServices/IncludeService.cs b/src/JsonApiDotNetCore/QueryParameterServices/IncludeService.cs
@@ -9,7 +9,6 @@
 
 namespace JsonApiDotNetCore.Query
 {
-
     public class IncludeService : QueryParameterService, IIncludeService
     {
         /// todo: use read-only lists.
diff --git a/src/JsonApiDotNetCore/QueryParameterServices/OmitDefaultService.cs b/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)
diff --git a/src/JsonApiDotNetCore/QueryParameterServices/OmitNullService.cs b/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)
diff --git a/src/JsonApiDotNetCore/QueryParameterServices/PageService.cs b/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()
         {
diff --git a/src/JsonApiDotNetCore/QueryParameterServices/SortService.cs b/src/JsonApiDotNetCore/QueryParameterServices/SortService.cs
@@ -8,6 +8,7 @@
 
 namespace JsonApiDotNetCore.Query
 {
+    /// <inheritdoc/>
     public class SortService : QueryParameterService, ISortService
     {
         const char DESCENDING_SORT_OPERATOR = '-';

Original file line number	Diff line number	Diff line change
`@@ -3,7 +3,6 @@`
`3`	`3`
`4`	`4`	`namespace JsonApiDotNetCoreExample.Controllers.Restricted`
`5`	`5`	`{`
`6`		`-`
`7`	`6`	`[Route("[controller]")]`
`8`	`7`	`[HttpReadOnly]`
`9`	`8`	`public class ReadOnlyController : ControllerBase`
Original file line number	Diff line number	Diff line change
`@@ -16,7 +16,19 @@ namespace JsonApiDotNetCoreExample.Services`
`16`	`16`	`{`
`17`	`17`	`public class CustomArticleService : EntityResourceService<Article>`
`18`	`18`	`{`
`19`		- 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)
	`19`	`+ public CustomArticleService(ISortService sortService,`
	`20`	`+ IFilterService filterService,`
	`21`	`+ IEntityRepository<Article, int> repository,`
	`22`	`+ IJsonApiOptions options,`
	`23`	`+ ICurrentRequest currentRequest,`
	`24`	`+ IIncludeService includeService,`
	`25`	`+ ISparseFieldsService sparseFieldsService,`
	`26`	`+ IPageService pageManager,`
	`27`	`+ IResourceGraph resourceGraph,`
	`28`	`+ IResourceHookExecutor hookExecutor = null,`
	`29`	`+ ILoggerFactory loggerFactory = null)`
	`30`	`+ : base(sortService, filterService, repository, options, currentRequest, includeService, sparseFieldsService,`
	`31`	`+ pageManager, resourceGraph, hookExecutor, loggerFactory)`
`20`	`32`	`{`
`21`	`33`	`}`
`22`	`34`
Original file line number	Diff line number	Diff line change
`@@ -3,12 +3,22 @@`
`3`	`3`	`namespace JsonApiDotNetCore.Controllers`
`4`	`4`	`{`
`5`	`5`	`public class DisableQueryAttribute : Attribute`
`6`		`- {`
	`6`	`+ {`
	`7`	`+ /// <summary>`
	`8`	`+ /// Disabled one of the native query parameters for a controller.`
	`9`	`+ /// </summary>`
	`10`	`+ /// <param name="queryParams"></param>`
`7`	`11`	`public DisableQueryAttribute(QueryParams queryParams)`
`8`	`12`	`{`
`9`	`13`	`QueryParams = queryParams.ToString("G").ToLower();`
`10`	`14`	`}`
`11`	`15`
	`16`	`+ /// <summary>`
	`17`	`+ /// It is allowed to use strings to indicate which query parameters`
	`18`	`+ /// should be disabled, because the user may have defined a custom`
	`19`	`+ /// query parameter that is not included in the <see cref="QueryParams"/> enum.`
	`20`	`+ /// </summary>`
	`21`	`+ /// <param name="customQueryParams"></param>`
`12`	`22`	`public DisableQueryAttribute(string customQueryParams)`
`13`	`23`	`{`
`14`	`24`	`QueryParams = customQueryParams.ToLower();`
Original file line number	Diff line number	Diff line change
`@@ -1,17 +1,11 @@`
`1`	`1`	`namespace JsonApiDotNetCore.Internal.Query`
`2`	`2`	`{`
`3`	`3`	`public static class QueryConstants {`
`4`		`- public const string FILTER = "filter";`
`5`		`- public const string SORT = "sort";`
`6`		`- public const string INCLUDE = "include";`
`7`		`- public const string PAGE = "page";`
`8`		`- public const string FIELDS = "fields";`
`9`	`4`	`public const char OPEN_BRACKET = '[';`
`10`	`5`	`public const char CLOSE_BRACKET = ']';`
`11`	`6`	`public const char COMMA = ',';`
`12`	`7`	`public const char COLON = ':';`
`13`	`8`	`public const string COLON_STR = ":";`
`14`	`9`	`public const char DOT = '.';`
`15`		`-`
`16`	`10`	`}`
`17`	`11`	`}`
Original file line number	Diff line number	Diff line change
`@@ -7,7 +7,7 @@ namespace JsonApiDotNetCore.Services`
`7`	`7`	`/// Responsible for populating the various service implementations of`
`8`	`8`	`/// <see cref="IQueryParameterService"/>.`
`9`	`9`	`/// </summary>`
`10`		`- public interface IQueryParameterParser`
	`10`	`+ public interface IQueryParameterDiscovery`
`11`	`11`	`{`
`12`	`12`	`void Parse(IQueryCollection query, DisableQueryAttribute disabledQuery = null);`
`13`	`13`	`}`
Original file line number	Diff line number	Diff line change
`@@ -64,7 +64,6 @@ protected AttrAttribute GetAttribute(string target, RelationshipAttribute relati`
`64`	`64`	`return attribute;`
`65`	`65`	`}`
`66`	`66`
`67`		`-`
`68`	`67`	`/// <summary>`
`69`	`68`	`/// Helper method for parsing query parameters into relationships attributes`
`70`	`69`	`/// </summary>`
Original file line number	Diff line number	Diff line change
`@@ -3,8 +3,14 @@`
`3`	`3`
`4`	`4`	`namespace JsonApiDotNetCore.Query`
`5`	`5`	`{`
	`6`	`+ /// <summary>`
	`7`	`+ /// Query parameter service responsible for url queries of the form ?filter[X]=Y`
	`8`	`+ /// </summary>`
`6`	`9`	`public interface IFilterService : IQueryParameterService`
`7`	`10`	`{`
	`11`	`+ /// <summary>`
	`12`	`+ /// Gets the parsed filter queries`
	`13`	`+ /// </summary>`
`8`	`14`	`List<FilterQueryContext> Get();`
`9`	`15`	`}`
`10`	`16`	`}`