Added additional explaining comments as requested in review feedback. Renamed QueryParser to QueryExpressionParser, because that is the ultimate base expression type being produced.

Author: Bart Koelman

src/JsonApiDotNetCore/Internal/Queries/Parsing/FieldChainRequirements.cs

@@ -1,14 +1,34 @@
 using System;
+using JsonApiDotNetCore.Models.Annotation;
 
 namespace JsonApiDotNetCore.Internal.Queries.Parsing
 {
+    /// <summary>
+    /// Used internally when parsing subexpressions in the query string parsers to indicate requirements when resolving a chain of fields.
+    /// Note these may be interpreted differently or even discarded completely by the various parser implementations,
+    /// as they tend to better understand the characteristics of the entire expression being parsed.
+    /// </summary>
     [Flags]
     public enum FieldChainRequirements
     {
+        /// <summary>
+        /// Indicates a single <see cref="AttrAttribute"/>, optionally preceded by a chain of <see cref="RelationshipAttribute"/>s.
+        /// </summary>
         EndsInAttribute = 1,
+
+        /// <summary>
+        /// Indicates a single <see cref="HasOneAttribute"/>, optionally preceded by a chain of <see cref="RelationshipAttribute"/>s.
+        /// </summary>
         EndsInToOne = 2,
+
+        /// <summary>
+        /// Indicates a single <see cref="HasManyAttribute"/>, optionally preceded by a chain of <see cref="RelationshipAttribute"/>s.
+        /// </summary>
         EndsInToMany = 4,
 
+        /// <summary>
+        /// Indicates one or a chain of <see cref="RelationshipAttribute"/>s.
+        /// </summary>
         IsRelationship = EndsInToOne | EndsInToMany
     }
 }

src/JsonApiDotNetCore/Internal/Queries/Parsing/FilterParser.cs

@@ -10,7 +10,7 @@
 
 namespace JsonApiDotNetCore.Internal.Queries.Parsing
 {
-    public class FilterParser : QueryParser
+    public class FilterParser : QueryExpressionParser
     {
         private readonly IResourceFactory _resourceFactory;
         private readonly Action<ResourceFieldAttribute, ResourceContext, string> _validateSingleFieldCallback;

src/JsonApiDotNetCore/Internal/Queries/Parsing/IncludeParser.cs

@@ -7,7 +7,7 @@
 
 namespace JsonApiDotNetCore.Internal.Queries.Parsing
 {
-    public class IncludeParser : QueryParser
+    public class IncludeParser : QueryExpressionParser
     {
         private readonly Action<RelationshipAttribute, ResourceContext, string> _validateSingleRelationshipCallback;
         private ResourceContext _resourceContextInScope;

src/JsonApiDotNetCore/Internal/Queries/Parsing/PaginationParser.cs

@@ -7,7 +7,7 @@
 
 namespace JsonApiDotNetCore.Internal.Queries.Parsing
 {
-    public class PaginationParser : QueryParser
+    public class PaginationParser : QueryExpressionParser
     {
         private readonly Action<ResourceFieldAttribute, ResourceContext, string> _validateSingleFieldCallback;
         private ResourceContext _resourceContextInScope;

src/JsonApiDotNetCore/Internal/Queries/Parsing/QueryParser.cs renamed to src/JsonApiDotNetCore/Internal/Queries/Parsing/QueryExpressionParser.cs

@@ -7,15 +7,19 @@
 namespace JsonApiDotNetCore.Internal.Queries.Parsing
 {
     /// <summary>
-    /// Base class for parsing query string parameters.
+    /// The base class for parsing query string parameters, using the Recursive Descent algorithm.
     /// </summary>
-    public abstract class QueryParser
+    /// <remarks>
+    /// Uses a tokenizer to populate a stack of tokens, which is then manipulated from the various parsing routines for subexpressions.
+    /// Implementations should throw <see cref="QueryParseException"/> on invalid input.
+    /// </remarks>
+    public abstract class QueryExpressionParser
     {
         private protected ResourceFieldChainResolver ChainResolver { get; }
 
         protected Stack<Token> TokenStack { get; private set; }
 
-        protected QueryParser(IResourceContextProvider resourceContextProvider)
+        protected QueryExpressionParser(IResourceContextProvider resourceContextProvider)
         {
             ChainResolver = new ResourceFieldChainResolver(resourceContextProvider);
         }

src/JsonApiDotNetCore/Internal/Queries/Parsing/QueryStringParameterScopeParser.cs

@@ -6,7 +6,7 @@
 
 namespace JsonApiDotNetCore.Internal.Queries.Parsing
 {
-    public class QueryStringParameterScopeParser : QueryParser
+    public class QueryStringParameterScopeParser : QueryExpressionParser
     {
         private readonly FieldChainRequirements _chainRequirements;
         private readonly Action<ResourceFieldAttribute, ResourceContext, string> _validateSingleFieldCallback;

src/JsonApiDotNetCore/Internal/Queries/Parsing/ResourceFieldChainResolver.cs

@@ -6,6 +6,9 @@
 
 namespace JsonApiDotNetCore.Internal.Queries.Parsing
 {
+    /// <summary>
+    /// Provides helper methods to resolve a chain of fields (relationships and attributes) from the resource graph.
+    /// </summary>
     internal sealed class ResourceFieldChainResolver
     {
         private readonly IResourceContextProvider _resourceContextProvider;

src/JsonApiDotNetCore/Internal/Queries/Parsing/SortParser.cs

@@ -7,7 +7,7 @@
 
 namespace JsonApiDotNetCore.Internal.Queries.Parsing
 {
-    public class SortParser : QueryParser
+    public class SortParser : QueryExpressionParser
     {
         private readonly Action<ResourceFieldAttribute, ResourceContext, string> _validateSingleFieldCallback;
         private ResourceContext _resourceContextInScope;

src/JsonApiDotNetCore/Internal/Queries/Parsing/SparseFieldSetParser.cs

@@ -7,7 +7,7 @@
 
 namespace JsonApiDotNetCore.Internal.Queries.Parsing
 {
-    public class SparseFieldSetParser : QueryParser
+    public class SparseFieldSetParser : QueryExpressionParser
     {
         private readonly Action<AttrAttribute, ResourceContext, string> _validateSingleAttributeCallback;
         private ResourceContext _resourceContextInScope;