Update XML doc comment in backend projects

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

@@ -3,6 +3,8 @@ 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>
 public record CreateBreweryLocation(
     Guid CityId,
     string AddressLine1,

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

@@ -5,10 +5,14 @@ using MediatR;
 
 namespace Features.Breweries.Commands.CreateBrewery;
 
+/// <summary>Handles <see cref="CreateBreweryCommand" /> by persisting a new brewery post.</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>
+    /// <exception cref="Domain.Exceptions.NotFoundException">
+    ///     Thrown when <paramref name="request" />'s <c>PostedById</c> or <c>Location.CityId</c> does not exist.
+    /// </exception>
     public async Task<BreweryDto> Handle(
         CreateBreweryCommand request,
         CancellationToken cancellationToken

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

@@ -2,6 +2,7 @@ using FluentValidation;
 
 namespace Features.Breweries.Commands.CreateBrewery;
 
+/// <summary>Validates <see cref="CreateBreweryCommand" />.</summary>
 public class CreateBreweryValidator : AbstractValidator<CreateBreweryCommand>
 {
     public CreateBreweryValidator()

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

@@ -2,4 +2,5 @@ using MediatR;
 
 namespace Features.Breweries.Commands.DeleteBrewery;
 
+/// <summary>Deletes a brewery post. Bound directly from the route of <c>DELETE /api/brewery/{id}</c>.</summary>
 public record DeleteBreweryCommand(Guid BreweryPostId) : IRequest;

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

@@ -3,9 +3,13 @@ using MediatR;
 
 namespace Features.Breweries.Commands.DeleteBrewery;
 
+/// <summary>Handles <see cref="DeleteBreweryCommand" /> by deleting the corresponding brewery post.</summary>
 public class DeleteBreweryHandler(IBreweryRepository repository)
     : IRequestHandler<DeleteBreweryCommand>
 {
+    /// <exception cref="Domain.Exceptions.NotFoundException">
+    ///     Thrown when no brewery exists with <paramref name="request" />'s <c>BreweryPostId</c>.
+    /// </exception>
     public Task Handle(DeleteBreweryCommand request, CancellationToken cancellationToken)
     {
         return repository.DeleteAsync(request.BreweryPostId);

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

@@ -3,6 +3,11 @@ using MediatR;
 
 namespace Features.Breweries.Commands.UpdateBrewery;
 
+/// <summary>Location details for a brewery being updated.</summary>
+/// <param name="BreweryPostLocationId">
+///     Identifier of the existing location row, if any; a new row is created if none exists yet.
+/// </param>
+/// <param name="Coordinates">Raw binary representation of the brewery's geographic coordinates.</param>
 public record UpdateBreweryLocation(
     Guid BreweryPostLocationId,
     Guid CityId,

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

@@ -5,6 +5,7 @@ using MediatR;
 
 namespace Features.Breweries.Commands.UpdateBrewery;
 
+/// <summary>Handles <see cref="UpdateBreweryCommand" /> by persisting changes to an existing brewery post.</summary>
 public class UpdateBreweryHandler(IBreweryRepository repository)
     : IRequestHandler<UpdateBreweryCommand, BreweryDto>
 {

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

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

web/backend/Features/Features.Breweries/Controllers/BreweryController.cs

@@ -11,6 +11,7 @@ using Shared.Contracts;
 
 namespace Features.Breweries.Controllers;
 
+/// <summary>Exposes CRUD operations for brewery posts.</summary>
 /// <remarks>
 ///     Requires JWT authentication by default; <see cref="GetById" /> and <see cref="GetAll" /> opt out via
 ///     <c>[AllowAnonymous]</c>.
@@ -20,6 +21,7 @@ namespace Features.Breweries.Controllers;
 [Authorize(AuthenticationSchemes = "JWT")]
 public class BreweryController(IMediator mediator) : ControllerBase
 {
+    /// <summary>Retrieves a single brewery post by ID.</summary>
     /// <remarks>Allows anonymous access.</remarks>
     /// <returns><c>200 OK</c> with the brewery if found; otherwise <c>404 Not Found</c>.</returns>
     [AllowAnonymous]
@@ -39,6 +41,9 @@ public class BreweryController(IMediator mediator) : ControllerBase
         );
     }
 
+    /// <summary>Retrieves brewery posts, newest first.</summary>
+    /// <param name="limit">Maximum number of breweries to return. Unbounded if <see langword="null"/>.</param>
+    /// <param name="offset">Number of breweries to skip. Treated as zero if <see langword="null"/>.</param>
     /// <remarks>Allows anonymous access.</remarks>
     [AllowAnonymous]
     [HttpGet]
@@ -59,6 +64,7 @@ public class BreweryController(IMediator mediator) : ControllerBase
         );
     }
 
+    /// <summary>Creates a new brewery post.</summary>
     /// <returns><c>201 Created</c> with the newly created brewery.</returns>
     [HttpPost]
     public async Task<ActionResult<ResponseBody<BreweryDto>>> Create(
@@ -76,6 +82,7 @@ public class BreweryController(IMediator mediator) : ControllerBase
         );
     }
 
+    /// <summary>Updates an existing brewery post.</summary>
     /// <param name="id">Must match <paramref name="command" />'s <c>BreweryPostId</c>.</param>
     /// <returns>
     ///     <c>200 OK</c> with the updated brewery; <c>400 Bad Request</c> if the route ID does not match the
@@ -101,7 +108,8 @@ public class BreweryController(IMediator mediator) : ControllerBase
         );
     }
 
-    /// <returns><c>200 OK</c> confirming the deletion.</returns>
+    /// <summary>Deletes a brewery post.</summary>
+    /// <returns><c>200 OK</c> confirming the deletion; <c>404 Not Found</c> if no brewery exists with <paramref name="id" />.</returns>
     [HttpDelete("{id:guid}")]
     public async Task<ActionResult<ResponseBody>> Delete(Guid id)
     {

web/backend/Features/Features.Breweries/DependencyInjection/FeaturesBreweriesServiceCollectionExtensions.cs

@@ -3,8 +3,11 @@ using Microsoft.Extensions.DependencyInjection;
 
 namespace Features.Breweries.DependencyInjection;
 
+/// <summary>Registers the services required by the Breweries feature.</summary>
 public static class FeaturesBreweriesServiceCollectionExtensions
 {
+    /// <summary>Registers <see cref="IBreweryRepository" /> and its implementation.</summary>
+    /// <returns><paramref name="services" />, for chaining.</returns>
     public static IServiceCollection AddFeaturesBreweries(this IServiceCollection services)
     {
         services.AddScoped<IBreweryRepository, BreweryRepository>();

web/backend/Features/Features.Breweries/Dtos/BreweryDto.cs

@@ -1,5 +1,6 @@
 namespace Features.Breweries.Dtos;
 
+/// <summary>Location details of a brewery, as returned by the API.</summary>
 public class BreweryLocationDto
 {
     public Guid BreweryPostLocationId { get; set; }
@@ -18,6 +19,7 @@ public class BreweryLocationDto
     public byte[]? Coordinates { get; set; }
 }
 
+/// <summary>A brewery post, as returned by the API.</summary>
 public class BreweryDto
 {
     public Guid BreweryPostId { get; set; }
@@ -30,10 +32,12 @@ public class BreweryDto
 
     public DateTime CreatedAt { get; set; }
 
+    /// <summary>Gets or sets the date and time of the last edit, or <see langword="null"/> if never edited.</summary>
     public DateTime? UpdatedAt { get; set; }
 
     /// <summary>Gets or sets the row-version/concurrency token used to detect conflicting concurrent updates.</summary>
     public byte[]? Timer { get; set; }
 
+    /// <summary>Gets or sets the brewery's location, or <see langword="null"/> if none has been set.</summary>
     public BreweryLocationDto? Location { get; set; }
 }

web/backend/Features/Features.Breweries/Dtos/BreweryDtoMapper.cs

@@ -2,8 +2,13 @@ using Domain.Entities;
 
 namespace Features.Breweries.Dtos;
 
+/// <summary>Maps <see cref="BreweryPost" /> domain entities to <see cref="BreweryDto" />.</summary>
 public static class BreweryDtoMapper
 {
+    /// <summary>
+    ///     Converts a <see cref="BreweryPost" /> to its DTO representation, including its
+    ///     <see cref="BreweryDto.Location" /> if the entity has one.
+    /// </summary>
     public static BreweryDto ToDto(this BreweryPost brewery)
     {
         return new BreweryDto

web/backend/Features/Features.Breweries/Queries/GetAllBreweries/GetAllBreweriesHandler.cs

@@ -5,9 +5,11 @@ using MediatR;
 
 namespace Features.Breweries.Queries.GetAllBreweries;
 
+/// <summary>Handles <see cref="GetAllBreweriesQuery" /> by retrieving brewery posts, newest first.</summary>
 public class GetAllBreweriesHandler(IBreweryRepository repository)
     : IRequestHandler<GetAllBreweriesQuery, IEnumerable<BreweryDto>>
 {
+    /// <summary>Retrieves brewery posts, newest first, applying <see cref="GetAllBreweriesQuery" />'s paging.</summary>
     public async Task<IEnumerable<BreweryDto>> Handle(
         GetAllBreweriesQuery request,
         CancellationToken cancellationToken

web/backend/Features/Features.Breweries/Queries/GetAllBreweries/GetAllBreweriesQuery.cs

@@ -3,4 +3,7 @@ using MediatR;
 
 namespace Features.Breweries.Queries.GetAllBreweries;
 
+/// <summary>Retrieves brewery posts, newest first. Bound directly from the query string of <c>GET /api/brewery</c>.</summary>
+/// <param name="Limit">Maximum number of breweries to return. Unbounded if <see langword="null"/>.</param>
+/// <param name="Offset">Number of breweries to skip. Treated as zero if <see langword="null"/>.</param>
 public record GetAllBreweriesQuery(int? Limit, int? Offset) : IRequest<IEnumerable<BreweryDto>>;

web/backend/Features/Features.Breweries/Queries/GetBreweryById/GetBreweryByIdHandler.cs

@@ -5,9 +5,11 @@ using MediatR;
 
 namespace Features.Breweries.Queries.GetBreweryById;
 
+/// <summary>Handles <see cref="GetBreweryByIdQuery" /> by retrieving the matching brewery post.</summary>
 public class GetBreweryByIdHandler(IBreweryRepository repository)
     : IRequestHandler<GetBreweryByIdQuery, BreweryDto?>
 {
+    /// <summary>Retrieves the brewery post, or <see langword="null"/> if none exists with the given ID.</summary>
     public async Task<BreweryDto?> Handle(
         GetBreweryByIdQuery request,
         CancellationToken cancellationToken

web/backend/Features/Features.Breweries/Queries/GetBreweryById/GetBreweryByIdQuery.cs

@@ -3,4 +3,6 @@ using MediatR;
 
 namespace Features.Breweries.Queries.GetBreweryById;
 
+/// <summary>Retrieves a brewery post by ID. Bound directly from the route of <c>GET /api/brewery/{id}</c>.</summary>
+/// <remarks>Yields <see langword="null"/> if no brewery exists with the given <c>BreweryPostId</c>.</remarks>
 public record GetBreweryByIdQuery(Guid BreweryPostId) : IRequest<BreweryDto?>;

web/backend/Features/Features.Breweries/Repository/BreweryRepository.cs

@@ -26,10 +26,11 @@ public class BreweryRepository(ISqlConnectionFactory connectionFactory)
         "bp.BreweryPostID, bp.PostedByID, bp.BreweryName, bp.Description, bp.CreatedAt, bp.UpdatedAt, bp.Timer, "
         + "bpl.BreweryPostLocationID, bpl.CityID, bpl.AddressLine1, bpl.AddressLine2, bpl.PostalCode, bpl.Coordinates";
 
-    /// <summary>
-    ///     Retrieves a brewery post by ID, joined to its location. A brewery with no location row
-    ///     returns <c>null</c> (matches the previous stored procedure's <c>INNER JOIN</c> behavior).
-    /// </summary>
+    /// <inheritdoc/>
+    /// <remarks>
+    ///     Joins to the location table with an <c>INNER JOIN</c> (matching the previous stored procedure's
+    ///     behavior), which is why a brewery with no location row is treated as not found.
+    /// </remarks>
     public async Task<BreweryPost?> GetByIdAsync(Guid id)
     {
         await using DbConnection connection = await CreateConnection();
@@ -47,10 +48,7 @@ public class BreweryRepository(ISqlConnectionFactory connectionFactory)
         return await reader.ReadAsync() ? MapToEntity(reader) : null;
     }
 
-    /// <summary>
-    ///     Retrieves all brewery posts, optionally paginated, ordered by creation date descending. Posts
-    ///     without a location are included, with <see cref="BreweryPost.Location" /> left <c>null</c>.
-    /// </summary>
+    /// <inheritdoc/>
     public async Task<IEnumerable<BreweryPost>> GetAllAsync(int? limit, int? offset)
     {
         await using DbConnection connection = await CreateConnection();
@@ -75,15 +73,7 @@ public class BreweryRepository(ISqlConnectionFactory connectionFactory)
         return breweries;
     }
 
-    /// <summary>
-    ///     Updates a brewery post's name and description, and upserts or clears its location. When
-    ///     <paramref name="brewery" />.<c>Location</c> is <c>null</c>, any existing location for the
-    ///     brewery is removed.
-    /// </summary>
-    /// <exception cref="NotFoundException">Thrown when the brewery, or the given city, does not exist.</exception>
-    /// <exception cref="ConflictException">
-    ///     Thrown when <paramref name="brewery" />'s <c>Timer</c> no longer matches the stored row.
-    /// </exception>
+    /// <inheritdoc/>
     public async Task<BreweryPost> UpdateAsync(BreweryPost brewery)
     {
         await using DbConnection connection = await CreateConnection();
@@ -221,10 +211,7 @@ public class BreweryRepository(ISqlConnectionFactory connectionFactory)
             );
     }
 
-    /// <summary>
-    ///     Deletes a brewery post by ID. Its location and photos are removed via cascading foreign keys.
-    /// </summary>
-    /// <exception cref="NotFoundException">Thrown when no brewery exists with the given <paramref name="id" />.</exception>
+    /// <inheritdoc/>
     public async Task DeleteAsync(Guid id)
     {
         await using DbConnection connection = await CreateConnection();
@@ -237,11 +224,7 @@ public class BreweryRepository(ISqlConnectionFactory connectionFactory)
             throw new NotFoundException("Brewery not found.");
     }
 
-    /// <summary>Creates a new brewery post, including its location details.</summary>
-    /// <exception cref="ArgumentException">Thrown when <paramref name="brewery" /> has no <c>Location</c>.</exception>
-    /// <exception cref="NotFoundException">
-    ///     Thrown when <paramref name="brewery" />.<c>PostedById</c> or <c>Location.CityId</c> does not exist.
-    /// </exception>
+    /// <inheritdoc/>
     public async Task CreateAsync(BreweryPost brewery)
     {
         if (brewery.Location is null)

web/backend/Features/Features.Breweries/Repository/IBreweryRepository.cs

@@ -7,14 +7,25 @@ namespace Features.Breweries.Repository;
 /// </summary>
 public interface IBreweryRepository
 {
-    /// <summary>Returns <c>null</c> if no brewery post exists with the given ID.</summary>
+    /// <summary>
+    ///     Retrieves a brewery post by ID, joined to its location. Returns <c>null</c> if no brewery post
+    ///     exists with the given ID, or if it has no associated location.
+    /// </summary>
     Task<BreweryPost?> GetByIdAsync(Guid id);
 
+    /// <summary>
+    ///     Retrieves all brewery posts, optionally paginated, ordered by creation date descending. Posts
+    ///     without a location are included, with <see cref="BreweryPost.Location" /> left <c>null</c>.
+    /// </summary>
+    /// <param name="limit">Maximum number of rows to return. Unbounded if <see langword="null" />.</param>
+    /// <param name="offset">Number of rows to skip. Treated as zero if <see langword="null" />.</param>
     Task<IEnumerable<BreweryPost>> GetAllAsync(int? limit, int? offset);
 
     /// <summary>
-    ///     Updates a brewery post, enforcing optimistic concurrency via <paramref name="brewery" />'s
-    ///     <c>Timer</c>: the update is rejected if the row was modified since <c>Timer</c> was read.
+    ///     Updates a brewery post's name and description, and upserts or clears its location, enforcing
+    ///     optimistic concurrency via <paramref name="brewery" />'s <c>Timer</c>: the update is rejected
+    ///     if the row was modified since <c>Timer</c> was read. When <paramref name="brewery" />'s
+    ///     <c>Location</c> is <c>null</c>, any existing location for the brewery is removed.
     ///     Returns the freshly persisted brewery, including its new <c>Timer</c>.
     /// </summary>
     /// <exception cref="Domain.Exceptions.NotFoundException">
@@ -27,9 +38,14 @@ public interface IBreweryRepository
     /// </exception>
     Task<BreweryPost> UpdateAsync(BreweryPost brewery);
 
+    /// <summary>Deletes a brewery post by ID. Its location and photos are removed via cascading foreign keys.</summary>
+    /// <exception cref="Domain.Exceptions.NotFoundException">Thrown when no brewery exists with the given <paramref name="id" />.</exception>
     Task DeleteAsync(Guid id);
 
     /// <summary>Creates a new brewery post, including its location details.</summary>
     /// <exception cref="ArgumentException">Thrown when <paramref name="brewery" /> has no <c>Location</c>.</exception>
+    /// <exception cref="Domain.Exceptions.NotFoundException">
+    ///     Thrown when <paramref name="brewery" />'s <c>PostedById</c> or <c>Location.CityId</c> does not exist.
+    /// </exception>
     Task CreateAsync(BreweryPost brewery);
 }