Document the types in QueryExpression hierarchy

Author: bkoelman

src/JsonApiDotNetCore/Queries/Expressions/AnyExpression.cs

@@ -6,12 +6,24 @@
 namespace JsonApiDotNetCore.Queries.Expressions;
 
 /// <summary>
-/// Represents the "any" filter function, resulting from text such as: any(name,'Jack','Joe')
+/// This expression allows to test if an attribute value equals any of the specified constants. It represents the "any" filter function, resulting from
+/// text such as:
+/// <c>
+/// any(owner.name,'Jack','Joe','John')
+/// </c>
+/// .
 /// </summary>
 [PublicAPI]
 public class AnyExpression : FilterExpression
 {
+    /// <summary>
+    /// The attribute whose value to compare. Chain format: an optional list of to-one relationships, followed by an attribute.
+    /// </summary>
     public ResourceFieldChainExpression TargetAttribute { get; }
+
+    /// <summary>
+    /// One or more constants to compare the attribute's value against.
+    /// </summary>
     public IImmutableSet<LiteralConstantExpression> Constants { get; }
 
     public AnyExpression(ResourceFieldChainExpression targetAttribute, IImmutableSet<LiteralConstantExpression> constants)

src/JsonApiDotNetCore/Queries/Expressions/ComparisonExpression.cs

@@ -4,13 +4,38 @@
 namespace JsonApiDotNetCore.Queries.Expressions;
 
 /// <summary>
-/// Represents a comparison filter function, resulting from text such as: equals(name,'Joe')
+/// This expression allows to compare two operands using a comparison operator. It represents comparison filter functions, resulting from text such as:
+/// <c>
+/// equals(name,'Joe')
+/// </c>
+/// ,
+/// <c>
+/// equals(owner,null)
+/// </c>
+/// , or:
+/// <c>
+/// greaterOrEqual(count(upVotes),count(downVotes),'1')
+/// </c>
+/// .
 /// </summary>
 [PublicAPI]
 public class ComparisonExpression : FilterExpression
 {
+    /// <summary>
+    /// The operator used to compare <see cref="Left" /> and <see cref="Right" />.
+    /// </summary>
     public ComparisonOperator Operator { get; }
+
+    /// <summary>
+    /// The left-hand operand, which can be a function or a field chain. Chain format: an optional list of to-one relationships, followed by an attribute.
+    /// When comparing equality with null, the chain may also end in a to-one relationship.
+    /// </summary>
     public QueryExpression Left { get; }
+
+    /// <summary>
+    /// The right-hand operand, which can be a function, a field chain, a constant, or null (if the type of <see cref="Left" /> is nullable). Chain format:
+    /// an optional list of to-one relationships, followed by an attribute.
+    /// </summary>
     public QueryExpression Right { get; }
 
     public ComparisonExpression(ComparisonOperator @operator, QueryExpression left, QueryExpression right)

src/JsonApiDotNetCore/Queries/Expressions/CountExpression.cs

@@ -4,13 +4,24 @@
 namespace JsonApiDotNetCore.Queries.Expressions;
 
 /// <summary>
-/// Represents the "count" function, resulting from text such as: count(articles)
+/// This expression allows to determine the number of related resources in a to-many relationship. It represents the "count" function, resulting from
+/// text such as:
+/// <c>
+/// count(articles)
+/// </c>
+/// .
 /// </summary>
 [PublicAPI]
 public class CountExpression : FunctionExpression
 {
+    /// <summary>
+    /// The to-many relationship to count related resources for. Chain format: an optional list of to-one relationships, followed by a to-many relationship.
+    /// </summary>
     public ResourceFieldChainExpression TargetCollection { get; }
 
+    /// <summary>
+    /// The CLR type this function returns, which is always <see cref="int" />.
+    /// </summary>
     public override Type ReturnType { get; } = typeof(int);
 
     public CountExpression(ResourceFieldChainExpression targetCollection)

src/JsonApiDotNetCore/Queries/Expressions/FilterExpression.cs

@@ -5,5 +5,8 @@ namespace JsonApiDotNetCore.Queries.Expressions;
 /// </summary>
 public abstract class FilterExpression : FunctionExpression
 {
+    /// <summary>
+    /// The CLR type this function returns, which is always <see cref="bool" />.
+    /// </summary>
     public override Type ReturnType { get; } = typeof(bool);
 }

src/JsonApiDotNetCore/Queries/Expressions/FunctionExpression.cs

@@ -5,5 +5,8 @@ namespace JsonApiDotNetCore.Queries.Expressions;
 /// </summary>
 public abstract class FunctionExpression : QueryExpression
 {
+    /// <summary>
+    /// The CLR type this function returns.
+    /// </summary>
     public abstract Type ReturnType { get; }
 }

src/JsonApiDotNetCore/Queries/Expressions/HasExpression.cs

@@ -5,12 +5,29 @@
 namespace JsonApiDotNetCore.Queries.Expressions;
 
 /// <summary>
-/// Represents the "has" filter function, resulting from text such as: has(articles) or has(articles,equals(isHidden,'false'))
+/// This expression allows to test if a to-many relationship has related resources, optionally with a condition. It represents the "has" filter function,
+/// resulting from text such as:
+/// <c>
+/// has(articles)
+/// </c>
+/// , or:
+/// <c>
+/// has(articles,equals(isHidden,'false'))
+/// </c>
+/// .
 /// </summary>
 [PublicAPI]
 public class HasExpression : FilterExpression
 {
+    /// <summary>
+    /// The to-many relationship to determine related resources for. Chain format: an optional list of to-one relationships, followed by a to-many
+    /// relationship.
+    /// </summary>
     public ResourceFieldChainExpression TargetCollection { get; }
+
+    /// <summary>
+    /// An optional filter that is applied on the related resources. Any related resources that do not match the filter are ignored.
+    /// </summary>
     public FilterExpression? Filter { get; }
 
     public HasExpression(ResourceFieldChainExpression targetCollection, FilterExpression? filter)

src/JsonApiDotNetCore/Queries/Expressions/IdentifierExpression.cs

@@ -1,7 +1,7 @@
 namespace JsonApiDotNetCore.Queries.Expressions;
 
 /// <summary>
-/// Represents the base type for an identifier, such as a field/relationship name, a constant between quotes or <c>null</c>.
+/// Represents the base type for an identifier, such as a JSON:API attribute/relationship name, a constant value between quotes, or <c>null</c>.
 /// </summary>
 public abstract class IdentifierExpression : QueryExpression
 {

src/JsonApiDotNetCore/Queries/Expressions/IncludeElementExpression.cs

@@ -6,12 +6,23 @@
 namespace JsonApiDotNetCore.Queries.Expressions;
 
 /// <summary>
-/// Represents an element in <see cref="IncludeExpression" />.
+/// Represents an element in an <see cref="IncludeExpression" /> tree, resulting from text such as:
+/// <c>
+/// articles.revisions
+/// </c>
+/// .
 /// </summary>
 [PublicAPI]
 public class IncludeElementExpression : QueryExpression
 {
+    /// <summary>
+    /// The JSON:API relationship to include.
+    /// </summary>
     public RelationshipAttribute Relationship { get; }
+
+    /// <summary>
+    /// The direct children of this subtree. Can be empty.
+    /// </summary>
     public IImmutableSet<IncludeElementExpression> Children { get; }
 
     public IncludeElementExpression(RelationshipAttribute relationship)

src/JsonApiDotNetCore/Queries/Expressions/IncludeExpression.cs

@@ -4,7 +4,11 @@
 namespace JsonApiDotNetCore.Queries.Expressions;
 
 /// <summary>
-/// Represents an inclusion tree, resulting from text such as: owner,articles.revisions
+/// Represents an inclusion tree, resulting from text such as:
+/// <c>
+/// owner,articles.revisions
+/// </c>
+/// .
 /// </summary>
 [PublicAPI]
 public class IncludeExpression : QueryExpression
@@ -13,6 +17,9 @@ public class IncludeExpression : QueryExpression
 
     public static readonly IncludeExpression Empty = new();
 
+    /// <summary>
+    /// The direct children of this tree. Use <see cref="Empty" /> if there are no children.
+    /// </summary>
     public IImmutableSet<IncludeElementExpression> Elements { get; }
 
     public IncludeExpression(IImmutableSet<IncludeElementExpression> elements)

src/JsonApiDotNetCore/Queries/Expressions/IsTypeExpression.cs

@@ -6,14 +6,37 @@
 namespace JsonApiDotNetCore.Queries.Expressions;
 
 /// <summary>
-/// Represents the "isType" filter function, resulting from text such as: isType(,men), isType(creator,men) or
+/// This expression allows to test if a resource in an inheritance hierarchy can be upcast to a derived type, optionally with a condition where the
+/// derived type is accessible. It represents the "isType" filter function, resulting from text such as:
+/// <c>
+/// isType(,men)
+/// </c>
+/// ,
+/// <c>
+/// isType(creator,men)
+/// </c>
+/// , or:
+/// <c>
 /// isType(creator,men,equals(hasBeard,'true'))
+/// </c>
+/// .
 /// </summary>
 [PublicAPI]
 public class IsTypeExpression : FilterExpression
 {
+    /// <summary>
+    /// An optional to-one relationship to start from. Chain format: one or more to-one relationships.
+    /// </summary>
     public ResourceFieldChainExpression? TargetToOneRelationship { get; }
+
+    /// <summary>
+    /// The derived resource type to upcast to.
+    /// </summary>
     public ResourceType DerivedType { get; }
+
+    /// <summary>
+    /// An optional filter that the derived resource must match.
+    /// </summary>
     public FilterExpression? Child { get; }
 
     public IsTypeExpression(ResourceFieldChainExpression? targetToOneRelationship, ResourceType derivedType, FilterExpression? child)

src/JsonApiDotNetCore/Queries/Expressions/LiteralConstantExpression.cs

@@ -4,14 +4,17 @@
 namespace JsonApiDotNetCore.Queries.Expressions;
 
 /// <summary>
-/// Represents a non-null constant value, resulting from text such as: equals(firstName,'Jack')
+/// Represents a non-null constant value, resulting from text such as: <c>'Jack'</c>, <c>'123'</c>, or: <c>'true'</c>.
 /// </summary>
 [PublicAPI]
 public class LiteralConstantExpression : IdentifierExpression
 {
     // Only used to show the original input in errors and diagnostics. Not part of the semantic expression value.
     private readonly string _stringValue;
 
+    /// <summary>
+    /// The constant value. Call <see cref="object.GetType()" /> to determine the .NET runtime type.
+    /// </summary>
     public object TypedValue { get; }
 
     public LiteralConstantExpression(object typedValue)

src/JsonApiDotNetCore/Queries/Expressions/LogicalExpression.cs

@@ -6,12 +6,28 @@
 namespace JsonApiDotNetCore.Queries.Expressions;
 
 /// <summary>
-/// Represents a logical filter function, resulting from text such as: and(equals(title,'Work'),has(articles))
+/// This expression allows to test whether one or all of its boolean operands are true. It represents the logical AND/OR filter functions, resulting from
+/// text such as:
+/// <c>
+/// and(equals(title,'Work'),has(articles))
+/// </c>
+/// , or:
+/// <c>
+/// or(equals(title,'Work'),has(articles))
+/// </c>
+/// .
 /// </summary>
 [PublicAPI]
 public class LogicalExpression : FilterExpression
 {
+    /// <summary>
+    /// The operator used to compare <see cref="Terms" />.
+    /// </summary>
     public LogicalOperator Operator { get; }
+
+    /// <summary>
+    /// The list of one or more boolean operands.
+    /// </summary>
     public IImmutableList<FilterExpression> Terms { get; }
 
     public LogicalExpression(LogicalOperator @operator, params FilterExpression[] terms)

src/JsonApiDotNetCore/Queries/Expressions/MatchTextExpression.cs

@@ -5,13 +5,37 @@
 namespace JsonApiDotNetCore.Queries.Expressions;
 
 /// <summary>
-/// Represents a text-matching filter function, resulting from text such as: startsWith(name,'A')
+/// This expression allows partial matching on the value of a JSON:API attribute. It represents text-matching filter functions, resulting from text such
+/// as:
+/// <c>
+/// startsWith(name,'The')
+/// </c>
+/// ,
+/// <c>
+/// endsWith(name,'end.')
+/// </c>
+/// , or:
+/// <c>
+/// contains(name,'middle')
+/// </c>
+/// .
 /// </summary>
 [PublicAPI]
 public class MatchTextExpression : FilterExpression
 {
+    /// <summary>
+    /// The attribute whose value to match. Chain format: an optional list of to-one relationships, followed by an attribute.
+    /// </summary>
     public ResourceFieldChainExpression TargetAttribute { get; }
+
+    /// <summary>
+    /// The text to match the attribute's value against.
+    /// </summary>
     public LiteralConstantExpression TextValue { get; }
+
+    /// <summary>
+    /// The kind of matching to perform.
+    /// </summary>
     public TextMatchKind MatchKind { get; }
 
     public MatchTextExpression(ResourceFieldChainExpression targetAttribute, LiteralConstantExpression textValue, TextMatchKind matchKind)

src/JsonApiDotNetCore/Queries/Expressions/NotExpression.cs

@@ -4,11 +4,18 @@
 namespace JsonApiDotNetCore.Queries.Expressions;
 
 /// <summary>
-/// Represents the "not" filter function, resulting from text such as: not(equals(title,'Work'))
+/// This expression allows to test for the logical negation of its operand. It represents the "not" filter function, resulting from text such as:
+/// <c>
+/// not(equals(title,'Work'))
+/// </c>
+/// .
 /// </summary>
 [PublicAPI]
 public class NotExpression : FilterExpression
 {
+    /// <summary>
+    /// The filter whose value to negate.
+    /// </summary>
     public FilterExpression Child { get; }
 
     public NotExpression(FilterExpression child)

src/JsonApiDotNetCore/Queries/Expressions/NullConstantExpression.cs

@@ -4,11 +4,14 @@
 namespace JsonApiDotNetCore.Queries.Expressions;
 
 /// <summary>
-/// Represents the constant <c>null</c>, resulting from text such as: equals(lastName,null)
+/// Represents the constant <c>null</c>, resulting from the text: <c>null</c>.
 /// </summary>
 [PublicAPI]
 public class NullConstantExpression : IdentifierExpression
 {
+    /// <summary>
+    /// Provides access to the singleton instance.
+    /// </summary>
     public static readonly NullConstantExpression Instance = new();
 
     private NullConstantExpression()

src/JsonApiDotNetCore/Queries/Expressions/PaginationElementQueryStringValueExpression.cs

@@ -3,13 +3,28 @@
 namespace JsonApiDotNetCore.Queries.Expressions;
 
 /// <summary>
-/// Represents an element in <see cref="PaginationQueryStringValueExpression" />.
+/// Represents an element in <see cref="PaginationQueryStringValueExpression" />, resulting from text such as: <c>1</c>, or:
+/// <c>
+/// articles:2
+/// </c>
+/// .
 /// </summary>
 [PublicAPI]
 public class PaginationElementQueryStringValueExpression : QueryExpression
 {
+    /// <summary>
+    /// The relationship this pagination applies to. Chain format: zero or more relationships, followed by a to-many relationship.
+    /// </summary>
     public ResourceFieldChainExpression? Scope { get; }
+
+    /// <summary>
+    /// The numeric pagination value.
+    /// </summary>
     public int Value { get; }
+
+    /// <summary>
+    /// The zero-based position in the text of the query string parameter value.
+    /// </summary>
     public int Position { get; }
 
     public PaginationElementQueryStringValueExpression(ResourceFieldChainExpression? scope, int value, int position)