more doc updates

Author: pwelter34

src/Arbiter.CommandQuery/Queries/EntityContinuationQuery.cs

@@ -6,18 +6,40 @@
 namespace Arbiter.CommandQuery.Queries;
 
 /// <summary>
-/// A query for paging entities by continuation token based on an <see cref="EntitySelect"/>.
+/// Represents a query for retrieving paged entities using a continuation token based on an <see cref="EntitySelect"/>.
+/// The result of the query will be of type <see cref="EntityContinuationResult{TReadModel}"/>.
 /// </summary>
-/// <typeparam name="TReadModel">The type of the read model.</typeparam>
+/// <typeparam name="TReadModel">The type of the read model returned as the result of the query.</typeparam>
+/// <remarks>
+/// This query is typically used in scenarios where data needs to be retrieved in pages, with each page being identified
+/// by a continuation token. The <see cref="EntitySelect"/> allows filtering and sorting of the data.
+/// </remarks>
+/// <example>
+/// The following example demonstrates how to use the <see cref="EntityContinuationQuery{TReadModel}"/>:
+/// <code>
+/// var principal = new ClaimsPrincipal(new ClaimsIdentity(new[] { new Claim(ClaimTypes.Name, "JohnDoe") }));
+/// var entitySelect = new EntitySelect
+/// {
+///     Filter = new EntityFilter { Name = "Status", Operator = "eq", Value = "Active" },
+///     Sort = new List&lt;EntitySort&gt; { new EntitySort { Name = "Name", Direction = "asc" } }
+/// };
+///
+/// var query = new EntityContinuationQuery&lt;ProductReadModel&gt;(principal, entitySelect, pageSize: 20, continuationToken: "abc123");
+///
+/// // Send the query to the mediator instance
+/// var result = await mediator.Send(query);
+/// Console.WriteLine($"Continuation Token: {result?.ContinuationToken}");
+/// </code>
+/// </example>
 public record EntityContinuationQuery<TReadModel> : CacheableQueryBase<EntityContinuationResult<TReadModel>>
 {
     /// <summary>
     /// Initializes a new instance of the <see cref="EntityContinuationQuery{TReadModel}"/> class.
     /// </summary>
-    /// <param name="principal">The <see cref="ClaimsPrincipal"/> this query is run for</param>
-    /// <param name="query">The <see cref="EntitySelect"/> for this query</param>
-    /// <param name="pageSize">The page size for this query</param>
-    /// <param name="continuationToken">The continuation token for this query</param>
+    /// <param name="principal">The <see cref="ClaimsPrincipal"/> representing the user executing the query.</param>
+    /// <param name="query">The <see cref="EntitySelect"/> defining the filter and sort criteria for the query.</param>
+    /// <param name="pageSize">The number of items to retrieve per page.</param>
+    /// <param name="continuationToken">The continuation token for retrieving the next page of results.</param>
     public EntityContinuationQuery(ClaimsPrincipal? principal, EntitySelect? query, int pageSize = 10, string? continuationToken = null)
         : base(principal)
     {
@@ -27,19 +49,19 @@ public EntityContinuationQuery(ClaimsPrincipal? principal, EntitySelect? query,
     }
 
     /// <summary>
-    /// The <see cref="EntitySelect"/> for this query.
+    /// Gets the <see cref="EntitySelect"/> defining the filter and sort criteria for the query.
     /// </summary>
     [JsonPropertyName("query")]
     public EntitySelect Query { get; }
 
     /// <summary>
-    /// The page size for this query.
+    /// Gets the number of items to retrieve per page.
     /// </summary>
     [JsonPropertyName("pageSize")]
     public int PageSize { get; }
 
     /// <summary>
-    /// The continuation token for this query.
+    /// Gets the continuation token for retrieving the next page of results.
     /// </summary>
     [JsonPropertyName("continuationToken")]
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]

src/Arbiter.CommandQuery/Queries/EntityFilter.cs

@@ -5,50 +5,100 @@
 namespace Arbiter.CommandQuery.Queries;
 
 /// <summary>
-/// A filter for selecting entities.
+/// Represents a filter for selecting entities based on specific criteria.
 /// </summary>
+/// <remarks>
+/// This class is typically used in queries to define filtering criteria for entities. Filters can be combined using logical operators
+/// such as "and" or "or" and can include nested filters for complex queries.
+/// </remarks>
+/// <example>
+/// The following example demonstrates how to use the <see cref="EntityFilter"/> class as a basic filter:
+/// <code>
+/// var filter = new EntityFilter
+/// {
+///     Name = "Status",
+///     Operator = "eq",
+///     Value = "Active"
+/// };
+/// </code>
+/// The following example demonstrates how to use the <see cref="EntityFilter"/> class as group filter:
+/// <code>
+/// var filter = new EntityFilter
+/// {
+///     Logic = "and",
+///     Filters = new List&lt;EntityFilter&gt;
+///     {
+///         new EntityFilter { Name = "Priority", Operator = "gt", Value = 1 },
+///         new EntityFilter { Name = "Status", Operator = "eq", Value = "Active" }
+///     }
+/// };
+/// </code>
+/// </example>
 [JsonConverter(typeof(EntityFilterConverter))]
 public class EntityFilter
 {
     /// <summary>
-    /// The name of the field or property to filter on.
+    /// Gets or sets the name of the field or property to filter on.
     /// </summary>
+    /// <value>
+    /// The name of the field or property to filter on.
+    /// </value>
     [JsonPropertyName("name")]
     public string? Name { get; set; }
 
     /// <summary>
-    /// The operator to use for the filter. This can be "eq", "ne", "gt", "lt", "ge", "le", "contains", "startswith", or "endswith".
+    /// Gets or sets the operator to use for the filter. This can be "eq" (equals), "ne" (not equals), "gt" (greater than),
+    /// "lt" (less than), "ge" (greater than or equal), "le" (less than or equal), "contains", "startswith", or "endswith".
     /// </summary>
+    /// <value>
+    /// The operator to use for the filter.
+    /// </value>
     /// <seealso cref="EntityFilterOperators"/>
     [JsonPropertyName("operator")]
     public string? Operator { get; set; }
 
     /// <summary>
-    /// The value to filter on.
+    /// Gets or sets the value to filter on.
     /// </summary>
+    /// <value>
+    /// The value to filter on.
+    /// </value>
     [JsonPropertyName("value")]
     public object? Value { get; set; }
 
     /// <summary>
-    /// The logic to use for the filter.  This can be "and" or "or". Used with <see cref="Filters"/> property.
+    /// Gets or sets the logical operator to use for combining filters. This can be "and" or "or".
     /// </summary>
+    /// <value>
+    /// The logical operator to use for combining filters.
+    /// </value>
     /// <seealso cref="EntityFilterLogic"/>
     [JsonPropertyName("logic")]
     public string? Logic { get; set; }
 
     /// <summary>
-    /// The list filters to apply to the query.  The logic for these filters is defined by the <see cref="Logic"/> property.
+    /// Gets or sets the list of nested filters to apply to the query. The logic for these filters is defined by the <see cref="Logic"/> property.
     /// </summary>
+    /// <value>
+    /// The list of nested filters to apply to the query.
+    /// </value>
     [JsonPropertyName("filters")]
     public IList<EntityFilter>? Filters { get; set; }
 
     /// <summary>
-    /// Check if this filter is valid.  A filter is valid if it has a name or if it has a list of filters.
+    /// Determines whether this filter is valid. A filter is considered valid if it has a name or if it contains a list of valid nested filters.
     /// </summary>
-    /// <returns><see langword="true" /> if filter is valid; otherwise <see langword="false" /></returns>
+    /// <returns>
+    /// <see langword="true" /> if the filter is valid; otherwise, <see langword="false" />.
+    /// </returns>
     public bool IsValid() => Filters?.Any(f => f.IsValid()) == true || Name is not null;
 
-    /// <inheritdoc />
+    /// <summary>
+    /// Computes the hash code for the current <see cref="EntityFilter"/> instance.
+    /// </summary>
+    /// <returns>
+    /// A hash code for the current <see cref="EntityFilter"/> instance.
+    /// </returns>
     public override int GetHashCode()
     {
         var hash = new HashCode();

src/Arbiter.CommandQuery/Queries/EntityIdentifierQuery.cs

@@ -7,18 +7,34 @@
 namespace Arbiter.CommandQuery.Queries;
 
 /// <summary>
-/// A query for a single identifier.
+/// Represents a query for retrieving a single entity identified by a specific key.
+/// The result of the query will be of type <typeparamref name="TReadModel"/>.
 /// </summary>
-/// <typeparam name="TKey">The type of the key.</typeparam>
-/// <typeparam name="TReadModel">The type of the read model</typeparam>
+/// <typeparam name="TKey">The type of the key used to identify the entity.</typeparam>
+/// <typeparam name="TReadModel">The type of the read model returned as the result of the query.</typeparam>
+/// <remarks>
+/// This query is typically used in a CQRS (Command Query Responsibility Segregation) pattern to retrieve a single entity
+/// based on its unique identifier. It supports caching to optimize repeated queries for the same entity.
+/// </remarks>
+/// <example>
+/// The following example demonstrates how to use the <see cref="EntityIdentifierQuery{TKey, TReadModel}"/>:
+/// <code>
+/// var principal = new ClaimsPrincipal(new ClaimsIdentity(new[] { new Claim(ClaimTypes.Name, "JohnDoe") }));
+/// var query = new EntityIdentifierQuery&lt;int, ProductReadModel&gt;(principal, 123);
+///
+/// // Send the query to the mediator instance
+/// var result = await mediator.Send(query);
+/// Console.WriteLine($"Product Name: {result?.Name}");
+/// </code>
+/// </example>
 public record EntityIdentifierQuery<TKey, TReadModel> : CacheableQueryBase<TReadModel>
 {
     /// <summary>
     /// Initializes a new instance of the <see cref="EntityIdentifierQuery{TKey, TReadModel}"/> class.
     /// </summary>
-    /// <param name="principal">the <see cref="ClaimsPrincipal"/> this query is run for</param>
-    /// <param name="id">The identifier for this query.</param>
-    /// <exception cref="ArgumentNullException">When <paramref name="id"/> is null</exception>
+    /// <param name="principal">The <see cref="ClaimsPrincipal"/> representing the user executing the query.</param>
+    /// <param name="id">The identifier of the entity to retrieve.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="id"/> is <c>null</c>.</exception>
     public EntityIdentifierQuery(ClaimsPrincipal? principal, [NotNull] TKey id)
         : base(principal)
     {
@@ -28,18 +44,30 @@ public EntityIdentifierQuery(ClaimsPrincipal? principal, [NotNull] TKey id)
     }
 
     /// <summary>
-    /// Gets the identifier for this query.
+    /// Gets the identifier of the entity to retrieve.
     /// </summary>
+    /// <value>
+    /// The identifier of the entity to retrieve.
+    /// </value>
     [NotNull]
     [JsonPropertyName("id")]
     public TKey Id { get; }
 
-
-    /// <inheritdoc/>
+    /// <summary>
+    /// Generates a cache key for the query based on the identifier.
+    /// </summary>
+    /// <returns>
+    /// A string representing the cache key for the query.
+    /// </returns>
     public override string GetCacheKey()
         => CacheTagger.GetKey<TReadModel, TKey>(CacheTagger.Buckets.Identifier, Id);
 
-    /// <inheritdoc/>
+    /// <summary>
+    /// Gets the cache tag associated with the <typeparamref name="TReadModel"/>.
+    /// </summary>
+    /// <returns>
+    /// The cache tag for the <typeparamref name="TReadModel"/>, or <c>null</c> if no tag is available.
+    /// </returns>
     public override string? GetCacheTag()
         => CacheTagger.GetTag<TReadModel>();
 }

src/Arbiter.CommandQuery/Queries/EntityIdentifiersQuery.cs

@@ -7,18 +7,35 @@
 namespace Arbiter.CommandQuery.Queries;
 
 /// <summary>
-/// A query for a list of identifiers.
+/// Represents a query for retrieving multiple entities identified by a list of keys.
+/// The result of the query will be a collection of type <typeparamref name="TReadModel"/>.
 /// </summary>
-/// <typeparam name="TKey">The type of the key.</typeparam>
-/// <typeparam name="TReadModel">The type of the read model</typeparam>
+/// <typeparam name="TKey">The type of the keys used to identify the entities.</typeparam>
+/// <typeparam name="TReadModel">The type of the read model returned as the result of the query.</typeparam>
+/// <remarks>
+/// This query is typically used in a CQRS (Command Query Responsibility Segregation) pattern to retrieve multiple entities
+/// based on their unique identifiers. It supports caching to optimize repeated queries for the same set of entities.
+/// </remarks>
+/// <example>
+/// The following example demonstrates how to use the <see cref="EntityIdentifiersQuery{TKey, TReadModel}"/>:
+/// <code>
+/// var principal = new ClaimsPrincipal(new ClaimsIdentity(new[] { new Claim(ClaimTypes.Name, "JohnDoe") }));
+/// var ids = new List&lt;int&gt; { 1, 2, 3 };
+/// var query = new EntityIdentifiersQuery&lt;int, ProductReadModel&gt;(principal, ids);
+///
+/// // Send the query to the mediator instance
+/// var result = await mediator.Send(query);
+/// Console.WriteLine($"Retrieved {result?.Count} products.");
+/// </code>
+/// </example>
 public record EntityIdentifiersQuery<TKey, TReadModel> : CacheableQueryBase<IReadOnlyCollection<TReadModel>>
 {
     /// <summary>
     /// Initializes a new instance of the <see cref="EntityIdentifiersQuery{TKey, TReadModel}"/> class.
     /// </summary>
-    /// <param name="principal">the <see cref="ClaimsPrincipal"/> this query is run for</param>
-    /// <param name="ids">The list of identifiers for this query.</param>
-    /// <exception cref="ArgumentNullException">When <paramref name="ids"/> is null</exception>
+    /// <param name="principal">The <see cref="ClaimsPrincipal"/> representing the user executing the query.</param>
+    /// <param name="ids">The list of identifiers for the entities to retrieve.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="ids"/> is <c>null</c>.</exception>
     public EntityIdentifiersQuery(ClaimsPrincipal? principal, [NotNull] IReadOnlyCollection<TKey> ids)
         : base(principal)
     {
@@ -28,16 +45,21 @@ public EntityIdentifiersQuery(ClaimsPrincipal? principal, [NotNull] IReadOnlyCol
     }
 
     /// <summary>
-    /// Gets the list of identifiers for this query.
+    /// Gets the list of identifiers for the entities to retrieve.
     /// </summary>
     /// <value>
-    /// The list of identifiers for this query.
+    /// The list of identifiers for the entities to retrieve.
     /// </value>
     [NotNull]
     [JsonPropertyName("ids")]
     public IReadOnlyCollection<TKey> Ids { get; }
 
-    /// <inheritdoc/>
+    /// <summary>
+    /// Generates a cache key for the query based on the list of identifiers.
+    /// </summary>
+    /// <returns>
+    /// A string representing the cache key for the query.
+    /// </returns>
     public override string GetCacheKey()
     {
         var hash = new HashCode();
@@ -48,7 +70,12 @@ public override string GetCacheKey()
         return CacheTagger.GetKey<TReadModel, int>(CacheTagger.Buckets.Identifiers, hash.ToHashCode());
     }
 
-    /// <inheritdoc/>
+    /// <summary>
+    /// Gets the cache tag associated with the <typeparamref name="TReadModel"/>.
+    /// </summary>
+    /// <returns>
+    /// The cache tag for the <typeparamref name="TReadModel"/>, or <c>null</c> if no tag is available.
+    /// </returns>
     public override string? GetCacheTag()
         => CacheTagger.GetTag<TReadModel>();
 }