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

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()