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.");