Update doc comments in Features.Breweries source (#279)

web/backend/Features/Features.Breweries/Commands/CreateBrewery/CreateBreweryCommand.cs

@@ -4,8 +4,12 @@ using MediatR;
 
 namespace Features.Breweries.Commands.CreateBrewery;
 
-/// <summary>Location details for a brewery being created.</summary>
-/// <param name="Coordinates">Raw binary representation of the brewery's geographic coordinates.</param>
+/// <summary>
+///     Describes the location supplied when creating a brewery.
+/// </summary>
+/// <param name="Coordinates">
+///     Serialized geographic coordinates for the brewery.
+/// </param>
 public record CreateBreweryLocation(
     Guid CityId,
     string AddressLine1,
@@ -15,7 +19,7 @@ public record CreateBreweryLocation(
 );
 
 /// <summary>
-///     Creates a new brewery post. Bound directly from the request body of <c>POST /api/brewery</c>.
+///     Represents the application request used to create a brewery post.
 /// </summary>
 public record CreateBreweryCommand(
     Guid PostedById,
@@ -24,9 +28,11 @@ public record CreateBreweryCommand(
     CreateBreweryLocation Location
 ) : IRequest<BreweryDto>;
 
-/// <summary>Request body for <c>POST /api/brewery</c>. <c>PostedById</c> comes from the caller's JWT.</summary>
+/// <summary>
+///     Defines the client-supplied body for creating a brewery post.
+/// </summary>
 public record CreateBreweryRequest(
     string BreweryName,
     string Description,
     CreateBreweryLocation Location
-);
+);

web/backend/Features/Features.Breweries/Commands/CreateBrewery/CreateBreweryHandler.cs

@@ -5,13 +5,17 @@ using MediatR;
 
 namespace Features.Breweries.Commands.CreateBrewery;
 
-/// <summary>Handles <see cref="CreateBreweryCommand" /> by persisting a new brewery post.</summary>
+/// <summary>
+///     Persists brewery posts created through <see cref="CreateBreweryCommand" />.
+/// </summary>
 public class CreateBreweryHandler(IBreweryRepository repository)
     : IRequestHandler<CreateBreweryCommand, BreweryDto>
 {
-    /// <summary>Creates a new brewery post, generating new identifiers for the post and its location.</summary>
+    /// <summary>
+    ///     Creates the post and its associated location with new identifiers.
+    /// </summary>
     /// <exception cref="Domain.Exceptions.NotFoundException">
-    ///     Thrown when <paramref name="request" />'s <c>PostedById</c> or <c>Location.CityId</c> does not exist.
+    ///     Thrown if the posting user or the selected city cannot be found.
     /// </exception>
     public async Task<BreweryDto> Handle(
         CreateBreweryCommand request,
@@ -38,10 +42,6 @@ public class CreateBreweryHandler(IBreweryRepository repository)
 
         await repository.CreateAsync(entity);
 
-        // RowVersion is a DB-computed column, unset on the in-memory entity; re-fetch so callers
-        // get back the value needed for a subsequent optimistic-concurrency update. Uses
-        // CancellationToken.None since the write already committed: cancelling the caller's request
-        // at this point must not turn a successful creation into a thrown exception.
         BreweryPost created =
             await repository.GetByIdAsync(entity.BreweryPostId, CancellationToken.None)
             ?? throw new InvalidOperationException(

web/backend/Features/Features.Breweries/Commands/CreateBrewery/CreateBreweryValidator.cs

@@ -2,7 +2,9 @@ using FluentValidation;
 
 namespace Features.Breweries.Commands.CreateBrewery;
 
-/// <summary>Validates <see cref="CreateBreweryCommand" />.</summary>
+/// <summary>
+///     Applies creation rules to <see cref="CreateBreweryCommand" />.
+/// </summary>
 public class CreateBreweryValidator : AbstractValidator<CreateBreweryCommand>
 {
     public CreateBreweryValidator()
@@ -27,7 +29,6 @@ public class CreateBreweryValidator : AbstractValidator<CreateBreweryCommand>
 
         RuleFor(x => x.Location.AddressLine1)
             .NotEmpty()
-            .When(x => x.Location is not null)
             .WithMessage("Address line 1 is required.")
             .MaximumLength(256)
             .WithMessage("Address line 1 cannot exceed 256 characters.");

web/backend/Features/Features.Breweries/Commands/DeleteBrewery/DeleteBreweryCommand.cs

@@ -2,5 +2,7 @@ using MediatR;
 
 namespace Features.Breweries.Commands.DeleteBrewery;
 
-/// <summary>Deletes a brewery post. <see cref="BreweryPostId" /> is bound from the route of <c>DELETE /api/brewery/{id}</c>.</summary>
+/// <summary>
+///     Represents a request to delete a brewery post on behalf of a caller.
+/// </summary>
 public record DeleteBreweryCommand(Guid BreweryPostId, Guid RequestingUserId) : IRequest;

web/backend/Features/Features.Breweries/Commands/DeleteBrewery/DeleteBreweryHandler.cs

@@ -3,15 +3,20 @@ using MediatR;
 
 namespace Features.Breweries.Commands.DeleteBrewery;
 
-/// <summary>Handles <see cref="DeleteBreweryCommand" /> by deleting the corresponding brewery post.</summary>
+/// <summary>
+///     Processes <see cref="DeleteBreweryCommand" /> requests.
+/// </summary>
 public class DeleteBreweryHandler(IBreweryRepository repository)
     : IRequestHandler<DeleteBreweryCommand>
 {
+    /// <summary>
+    ///     Confirms that the caller owns the post before deleting it.
+    /// </summary>
     /// <exception cref="Domain.Exceptions.NotFoundException">
-    ///     Thrown when no brewery exists with <paramref name="request" />'s <c>BreweryPostId</c>.
+    ///     Thrown if the brewery post does not exist.
     /// </exception>
     /// <exception cref="Domain.Exceptions.ForbiddenException">
-    ///     Thrown when <paramref name="request" />'s <c>RequestingUserId</c> did not post the brewery.
+    ///     Thrown if the caller did not create the brewery post.
     /// </exception>
     public async Task Handle(DeleteBreweryCommand request, CancellationToken cancellationToken)
     {

web/backend/Features/Features.Breweries/Commands/UpdateBrewery/UpdateBreweryCommand.cs

@@ -4,11 +4,15 @@ using MediatR;
 
 namespace Features.Breweries.Commands.UpdateBrewery;
 
-/// <summary>Location details for a brewery being updated.</summary>
+/// <summary>
+///     Describes the location supplied when updating a brewery.
+/// </summary>
 /// <param name="BreweryPostLocationId">
-///     Identifier of the existing location row, if any; a new row is created if none exists yet.
+///     Identifies the existing location; a new location is created when needed.
+/// </param>
+/// <param name="Coordinates">
+///     Serialized geographic coordinates for the brewery.
 /// </param>
-/// <param name="Coordinates">Raw binary representation of the brewery's geographic coordinates.</param>
 public record UpdateBreweryLocation(
     Guid BreweryPostLocationId,
     Guid CityId,
@@ -19,9 +23,8 @@ public record UpdateBreweryLocation(
 );
 
 /// <summary>
-///     Updates an existing brewery post. A <c>null</c> <see cref="Location" /> clears the brewery's location.
-///     <see cref="RowVersion" /> must be the row-version last read for this brewery (e.g. from a prior
-///     <c>GET</c>); the update is rejected with a <c>409 Conflict</c> if the brewery was modified since then.
+///     Represents a concurrency-protected change to an existing brewery post.
+///     A <see langword="null" /> <see cref="Location" /> removes the existing location.
 /// </summary>
 public record UpdateBreweryCommand(
     Guid BreweryPostId,
@@ -32,7 +35,9 @@ public record UpdateBreweryCommand(
     UpdateBreweryLocation? Location
 ) : IRequest<BreweryDto>;
 
-/// <summary>Request body for <c>PUT /api/brewery/{id}</c>.</summary>
+/// <summary>
+///     Defines the client-supplied body for updating a brewery post.
+/// </summary>
 public record UpdateBreweryRequest(
     Guid BreweryPostId,
     byte[] RowVersion,
@@ -40,4 +45,3 @@ public record UpdateBreweryRequest(
     string Description,
     UpdateBreweryLocation? Location
 );
-

web/backend/Features/Features.Breweries/Commands/UpdateBrewery/UpdateBreweryHandler.cs

@@ -5,21 +5,20 @@ using MediatR;
 
 namespace Features.Breweries.Commands.UpdateBrewery;
 
-/// <summary>Handles <see cref="UpdateBreweryCommand" /> by persisting changes to an existing brewery post.</summary>
+/// <summary>
+///     Persists changes requested through <see cref="UpdateBreweryCommand" />.
+/// </summary>
 public class UpdateBreweryHandler(IBreweryRepository repository)
     : IRequestHandler<UpdateBreweryCommand, BreweryDto>
 {
     /// <summary>
-    ///     Updates an existing brewery post. If <paramref name="request" /> has no <c>Location</c>,
-    ///     the brewery's location is cleared.
+    ///     Updates the post after confirming that the caller owns it.
     /// </summary>
     /// <exception cref="Domain.Exceptions.NotFoundException">
-    ///     Thrown when no brewery exists with <paramref name="request" />'s <c>BreweryPostId</c>, or its
-    ///     location's <c>CityId</c> does not exist.
+    ///     Thrown if the brewery post or its requested city cannot be found.
     /// </exception>
     /// <exception cref="Domain.Exceptions.ConflictException">
-    ///     Thrown when the brewery was modified by another request since <paramref name="request" />.
-    ///     <c>RowVersion</c> was read.
+    ///     Thrown if the post has changed since its supplied row version was read.
     /// </exception>
     public async Task<BreweryDto> Handle(
         UpdateBreweryCommand request,

web/backend/Features/Features.Breweries/Commands/UpdateBrewery/UpdateBreweryValidator.cs

@@ -2,7 +2,9 @@ using FluentValidation;
 
 namespace Features.Breweries.Commands.UpdateBrewery;
 
-/// <summary>Validates <see cref="UpdateBreweryCommand" />.</summary>
+/// <summary>
+///     Applies update rules to <see cref="UpdateBreweryCommand" />.
+/// </summary>
 public class UpdateBreweryValidator : AbstractValidator<UpdateBreweryCommand>
 {
     public UpdateBreweryValidator()