improve docs

Author: pwelter34

src/Arbiter.CommandQuery/Commands/EntityCreateCommand.cs

@@ -7,25 +7,58 @@
 namespace Arbiter.CommandQuery.Commands;
 
 /// <summary>
-/// A command to create a new entity based on the specified <typeparamref name="TCreateModel"/>.
-/// <typeparamref name="TReadModel"/> will be the result of the command.
+/// Represents a command to create a new entity using the specified <typeparamref name="TCreateModel"/>.
+/// The result of the command will be of type <typeparamref name="TReadModel"/>.
 /// </summary>
-/// <typeparam name="TCreateModel">The type of the create model.</typeparam>
-/// <typeparam name="TReadModel">The type of the read model.</typeparam>
+/// <typeparam name="TCreateModel">The type of the create model used to provide data for the new entity.</typeparam>
+/// <typeparam name="TReadModel">The type of the read model returned as the result of the command.</typeparam>
+/// <remarks>
+/// This command is typically used in a CQRS (Command Query Responsibility Segregation) pattern to create a new entity
+/// and return a read model representing the created entity or a related result.
+/// </remarks>
+/// <example>
+/// The following example demonstrates how to use the <see cref="EntityCreateCommand{TCreateModel, TReadModel}"/>:
+/// <code>
+/// var createModel = new ProductCreateModel
+/// {
+///     Name = "New Product",
+///     Description = "A description of the new product",
+///     Price = 19.99m
+/// };
+///
+/// var principal = new ClaimsPrincipal(new ClaimsIdentity(new[] { new Claim(ClaimTypes.Name, "JohnDoe") }));
+///
+/// var command = new EntityCreateCommand&lt;ProductCreateModel, ProductReadModel&gt;(principal, createModel);
+///
+/// // Pass the command to the mediator for execution
+/// var result = await mediator.Send(command);
+/// Console.WriteLine($"Created product: {result?.Name}");
+/// </code>
+/// </example>
 public record EntityCreateCommand<TCreateModel, TReadModel>
     : EntityModelCommand<TCreateModel, TReadModel>, ICacheExpire
 {
     /// <summary>
     /// Initializes a new instance of the <see cref="EntityCreateCommand{TCreateModel, TReadModel}"/> class.
     /// </summary>
-    /// <param name="principal">The <see cref="ClaimsPrincipal"/> this command is run for</param>
-    /// <param name="model">The create model for this command.</param>
+    /// <param name="principal">The <see cref="ClaimsPrincipal"/> representing the user for whom this command is executed.</param>
+    /// <param name="model">The create model containing the data for the new entity.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="model"/> is <c>null</c>.</exception>
     public EntityCreateCommand(ClaimsPrincipal? principal, [NotNull] TCreateModel model)
         : base(principal, model)
     {
     }
 
-    /// <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>
+    /// <example>
+    /// The following example demonstrates how to retrieve the cache tag:
+    /// <code>
+    /// var cacheTag = command.GetCacheTag();
+    /// </code>
+    /// </example>
     string? ICacheExpire.GetCacheTag()
         => CacheTagger.GetTag<TReadModel>();
 }

src/Arbiter.CommandQuery/Commands/EntityDeleteCommand.cs

@@ -7,24 +7,48 @@
 namespace Arbiter.CommandQuery.Commands;
 
 /// <summary>
-/// A command to delete based on the specified identifier.
-/// <typeparamref name="TReadModel"/> will be the result of the command.
+/// A command to delete an entity based on the specified identifier.
+/// <typeparamref name="TReadModel"/> represents the result of the command.
 /// </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 after the command execution.</typeparam>
+/// <remarks>
+/// This command is typically used in a CQRS (Command Query Responsibility Segregation) pattern to delete an entity
+/// and optionally return a read model representing the deleted entity or a related result.
+/// </remarks>
+/// <example>
+/// The following example demonstrates how to use the <see cref="EntityDeleteCommand{TKey, TReadModel}"/>:
+/// <code>
+/// var principal = new ClaimsPrincipal(new ClaimsIdentity(new[] { new Claim(ClaimTypes.Name, "JohnDoe") }));
+/// var command = new EntityDeleteCommand&lt;int, ProductReadModel&gt;(principal, 123);
+///
+/// // Pass the command to a handler or mediator
+/// var result = await mediator.Send(command);
+/// </code>
+/// </example>
 public record EntityDeleteCommand<TKey, TReadModel>
     : EntityIdentifierCommand<TKey, TReadModel>, ICacheExpire
 {
     /// <summary>
     /// Initializes a new instance of the <see cref="EntityDeleteCommand{TKey, TReadModel}"/> class.
     /// </summary>
-    /// <param name="principal">the <see cref="ClaimsPrincipal" /> this command is run for</param>
-    /// <param name="id">The identifier for this command.</param>
+    /// <param name="principal">The <see cref="ClaimsPrincipal"/> representing the user executing the command.</param>
+    /// <param name="id">The identifier of the entity to be deleted.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="id"/> is null.</exception>
     public EntityDeleteCommand(ClaimsPrincipal? principal, [NotNull] TKey id) : base(principal, id)
     {
     }
 
-    /// <inheritdoc />
+    /// <summary>
+    /// Gets the cache tag for the entity associated with this command.
+    /// </summary>
+    /// <returns>The cache tag for the entity, or <c>null</c> if no tag is available.</returns>
+    /// <example>
+    /// The following example demonstrates how to retrieve the cache tag:
+    /// <code>
+    /// var cacheTag = command.GetCacheTag();
+    /// </code>
+    /// </example>
     string? ICacheExpire.GetCacheTag()
         => CacheTagger.GetTag<TReadModel>();
 }

src/Arbiter.CommandQuery/Commands/EntityIdentifierCommand.cs

@@ -5,19 +5,42 @@
 namespace Arbiter.CommandQuery.Commands;
 
 /// <summary>
-/// A base command for commands that use an identifier
+/// Represents a base command for operations that require an identifier.
 /// </summary>
-/// <typeparam name="TKey">The type of the key.</typeparam>
-/// <typeparam name="TResponse">The type of the response.</typeparam>
+/// <typeparam name="TKey">The type of the key used to identify the entity.</typeparam>
+/// <typeparam name="TResponse">The type of the response returned by the command.</typeparam>
+/// <remarks>
+/// This class is typically used in a CQRS (Command Query Responsibility Segregation) pattern to define commands
+/// that operate on a specific entity identified by a key.
+/// </remarks>
+/// <example>
+/// The following example demonstrates how to use the <see cref="EntityIdentifierCommand{TKey, TResponse}"/>:
+/// <code>
+/// public record GetEntityByIdCommand : EntityIdentifierCommand&lt;int, ProductReadModel&gt;
+/// {
+///     public GetEntityByIdCommand(ClaimsPrincipal principal, int id)
+///         : base(principal, id)
+///     {
+///     }
+/// }
+///
+/// var principal = new ClaimsPrincipal(new ClaimsIdentity(new[] { new Claim(ClaimTypes.Name, "JohnDoe") }));
+/// var command = new GetEntityByIdCommand(principal, 123);
+///
+/// // Pass the command to a handler or mediator
+/// var result = await mediator.Send(command);
+/// Console.WriteLine($"Entity Name: {result?.Name}");
+/// </code>
+/// </example>
 public abstract record EntityIdentifierCommand<TKey, TResponse>
     : PrincipalCommandBase<TResponse>
 {
     /// <summary>
     /// Initializes a new instance of the <see cref="EntityIdentifierCommand{TKey, TResponse}"/> class.
     /// </summary>
-    /// <param name="principal">the <see cref="ClaimsPrincipal"/> this command is run for</param>
-    /// <param name="id">The identifier for this command.</param>
-    /// <exception cref="ArgumentNullException">When <paramref name="id"/> is null</exception>
+    /// <param name="principal">The <see cref="ClaimsPrincipal"/> representing the user executing the command.</param>
+    /// <param name="id">The identifier of the entity for this command.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="id"/> is <see langword="null"/>.</exception>
     protected EntityIdentifierCommand(ClaimsPrincipal? principal, [NotNull] TKey id)
         : base(principal)
     {
@@ -30,7 +53,7 @@ protected EntityIdentifierCommand(ClaimsPrincipal? principal, [NotNull] TKey id)
     /// Gets the identifier for this command.
     /// </summary>
     /// <value>
-    /// The identifier for this command.
+    /// The identifier of the entity for this command.
     /// </value>
     [NotNull]
     [JsonPropertyName("id")]

src/Arbiter.CommandQuery/Commands/EntityIdentifiersCommand.cs

@@ -5,19 +5,42 @@
 namespace Arbiter.CommandQuery.Commands;
 
 /// <summary>
-/// A base command for commands that use a list of identifiers
+/// Represents a base command for operations that require a list of identifiers.
 /// </summary>
-/// <typeparam name="TKey">The type of the key.</typeparam>
-/// <typeparam name="TResponse">The type of the response.</typeparam>
+/// <typeparam name="TKey">The type of the key used to identify the entities.</typeparam>
+/// <typeparam name="TResponse">The type of the response returned by the command.</typeparam>
+/// <remarks>
+/// This class is typically used in a CQRS (Command Query Responsibility Segregation) pattern to define commands
+/// that operate on multiple entities identified by a collection of keys.
+/// </remarks>
+/// <example>
+/// The following example demonstrates how to use the <see cref="EntityIdentifiersCommand{TKey, TResponse}"/>:
+/// <code>
+/// public record DeleteEntitiesCommand : EntityIdentifiersCommand&lt;int, ProductReadModel&gt;
+/// {
+///     public DeleteEntitiesCommand(ClaimsPrincipal principal, IReadOnlyCollection&lt;int&gt; ids)
+///         : base(principal, ids)
+///     {
+///     }
+/// }
+///
+/// var principal = new ClaimsPrincipal(new ClaimsIdentity(new[] { new Claim(ClaimTypes.Name, "JohnDoe") }));
+/// var command = new DeleteEntitiesCommand(principal, new List&lt;int&gt; { 1, 2, 3 });
+///
+/// // Pass the command to a handler or mediator
+/// var result = await mediator.Send(command);
+/// Console.WriteLine($"Entities deleted: {result}");
+/// </code>
+/// </example>
 public abstract record EntityIdentifiersCommand<TKey, TResponse>
     : PrincipalCommandBase<TResponse>
 {
     /// <summary>
     /// Initializes a new instance of the <see cref="EntityIdentifiersCommand{TKey, TResponse}"/> class.
     /// </summary>
-    /// <param name="principal">the <see cref="ClaimsPrincipal"/> this command is run for</param>
-    /// <param name="ids">The list of identifiers for this command.</param>
-    /// <exception cref="ArgumentNullException">When <paramref name="ids"/> is null</exception>
+    /// <param name="principal">The <see cref="ClaimsPrincipal"/> representing the user executing the command.</param>
+    /// <param name="ids">The collection of identifiers for this command.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="ids"/> is <c>null</c>.</exception>
     protected EntityIdentifiersCommand(ClaimsPrincipal? principal, [NotNull] IReadOnlyCollection<TKey> ids)
         : base(principal)
     {
@@ -27,10 +50,10 @@ protected EntityIdentifiersCommand(ClaimsPrincipal? principal, [NotNull] IReadOn
     }
 
     /// <summary>
-    /// Gets the list of identifiers for this command.
+    /// Gets the collection of identifiers for this command.
     /// </summary>
     /// <value>
-    /// The list of identifiers for this command.
+    /// The collection of identifiers for this command.
     /// </value>
     [JsonPropertyName("ids")]
     public IReadOnlyCollection<TKey> Ids { get; }

src/Arbiter.CommandQuery/Commands/EntityModelCommand.cs

@@ -5,18 +5,49 @@
 namespace Arbiter.CommandQuery.Commands;
 
 /// <summary>
-/// Base class for using a view model for the command
+/// Represents a base command that uses a view model to perform an operation.
 /// </summary>
-/// <typeparam name="TEntityModel">The type of the model for this command.</typeparam>
-/// <typeparam name="TReadModel">The type of the read model to return.</typeparam>
+/// <typeparam name="TEntityModel">The type of the model used as input for the command.</typeparam>
+/// <typeparam name="TReadModel">The type of the read model returned as the result of the command.</typeparam>
+/// <remarks>
+/// This class is typically used in a CQRS (Command Query Responsibility Segregation) pattern to define commands
+/// that operate on an entity using a model and return a read model as the result.
+/// </remarks>
+/// <example>
+/// The following example demonstrates how to use the <see cref="EntityModelCommand{TEntityModel, TReadModel}"/>:
+/// <code>
+/// public record CreateProductCommand : EntityModelCommand&lt;ProductCreateModel, ProductReadModel&gt;
+/// {
+///     public CreateProductCommand(ClaimsPrincipal principal, ProductCreateModel model)
+///         : base(principal, model)
+///     {
+///     }
+/// }
+///
+/// var createModel = new ProductCreateModel
+/// {
+///     Name = "New Product",
+///     Description = "A description of the new product",
+///     Price = 19.99m
+/// };
+///
+/// var principal = new ClaimsPrincipal(new ClaimsIdentity(new[] { new Claim(ClaimTypes.Name, "JohnDoe") }));
+/// var command = new CreateProductCommand(principal, createModel);
+///
+/// // Pass the command to a handler or mediator
+/// var result = await mediator.Send(command);
+/// Console.WriteLine($"Created product: {result?.Name}");
+/// </code>
+/// </example>
 public abstract record EntityModelCommand<TEntityModel, TReadModel>
     : PrincipalCommandBase<TReadModel>
 {
     /// <summary>
     /// Initializes a new instance of the <see cref="EntityModelCommand{TEntityModel, TReadModel}"/> class.
     /// </summary>
-    /// <param name="principal">the <see cref="ClaimsPrincipal"/> this command is run for</param>
-    /// <param name="model">The model to use for this command.</param>
+    /// <param name="principal">The <see cref="ClaimsPrincipal"/> representing the user executing the command.</param>
+    /// <param name="model">The model containing the data for the operation.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="model"/> is <c>null</c>.</exception>
     protected EntityModelCommand(ClaimsPrincipal? principal, [NotNull] TEntityModel model)
         : base(principal)
     {
@@ -26,10 +57,10 @@ protected EntityModelCommand(ClaimsPrincipal? principal, [NotNull] TEntityModel
     }
 
     /// <summary>
-    /// Gets the view model to use for this command.
+    /// Gets the view model used for this command.
     /// </summary>
     /// <value>
-    /// The view model to use for this command.
+    /// The view model containing the data for the operation.
     /// </value>
     [NotNull]
     [JsonPropertyName("model")]

src/Arbiter.CommandQuery/Commands/EntityPatchCommand.cs

@@ -10,21 +10,39 @@
 namespace Arbiter.CommandQuery.Commands;
 
 /// <summary>
-/// A command to apply a JSON patch to the entity with the specified identifier.
-/// <typeparamref name="TReadModel"/> will be the result of the command.
+/// Represents a command to apply a JSON patch to an entity identified by a specific key.
+/// The result of the command 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 command.</typeparam>
+/// <remarks>
+/// This command is typically used in a CQRS (Command Query Responsibility Segregation) pattern to apply partial updates
+/// to an entity using a JSON patch document.
+/// </remarks>
+/// <example>
+/// The following example demonstrates how to use the <see cref="EntityPatchCommand{TKey, TReadModel}"/>:
+/// <code>
+/// var patchDocument = new JsonPatchDocument();
+/// patchDocument.Replace("/Name", "Updated Name");
+///
+/// var principal = new ClaimsPrincipal(new ClaimsIdentity(new[] { new Claim(ClaimTypes.Name, "JohnDoe") }));
+/// var command = new EntityPatchCommand&lt;int, ProductReadModel&gt;(principal, 123, patchDocument);
+///
+/// // Pass the command to a handler or mediator
+/// var result = await mediator.Send(command);
+/// Console.WriteLine($"Updated product name: {result?.Name}");
+/// </code>
+/// </example>
 public record EntityPatchCommand<TKey, TReadModel>
     : EntityIdentifierCommand<TKey, TReadModel>, ICacheExpire
 {
     /// <summary>
     /// Initializes a new instance of the <see cref="EntityPatchCommand{TKey, TReadModel}"/> class.
     /// </summary>
-    /// <param name="principal">the <see cref="ClaimsPrincipal" /> this command is run for</param>
-    /// <param name="id">The identifier to apply JSON patch to.</param>
-    /// <param name="patch">The JSON patch to apply.</param>
-    /// <exception cref="ArgumentNullException">When <paramref name="id"/> or <paramref name="patch"/> is null</exception>
+    /// <param name="principal">The <see cref="ClaimsPrincipal"/> representing the user executing the command.</param>
+    /// <param name="id">The identifier of the entity to which the JSON patch will be applied.</param>
+    /// <param name="patch">The JSON patch document containing the updates to apply.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="id"/> or <paramref name="patch"/> is <c>null</c>.</exception>
     public EntityPatchCommand(ClaimsPrincipal? principal, [NotNull] TKey id, [NotNull] JsonPatchDocument patch)
         : base(principal, id)
     {
@@ -34,15 +52,24 @@ public EntityPatchCommand(ClaimsPrincipal? principal, [NotNull] TKey id, [NotNul
     }
 
     /// <summary>
-    /// Gets the JSON patch to apply to the entity with the specified identifier.
+    /// Gets the JSON patch document to apply to the entity with the specified identifier.
     /// </summary>
     /// <value>
-    /// The patch.
+    /// The JSON patch document containing the updates.
     /// </value>
     [JsonPropertyName("patch")]
     public JsonPatchDocument Patch { get; }
 
-    /// <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>
+    /// <example>
+    /// The following example demonstrates how to retrieve the cache tag:
+    /// <code>
+    /// var cacheTag = command.GetCacheTag();
+    /// </code>
+    /// </example>
     string? ICacheExpire.GetCacheTag()
         => CacheTagger.GetTag<TReadModel>();
 }