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

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

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

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

@@ -3,7 +3,13 @@ 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>
+/// <summary>
+///     Requests brewery posts ordered from newest to oldest.
+/// </summary>
+/// <param name="Limit">
+///     Caps the result count; <see langword="null" /> disables the cap.
+/// </param>
+/// <param name="Offset">
+///     Specifies the number of results to skip; <see langword="null" /> means zero.
+/// </param>
 public record GetAllBreweriesQuery(int? Limit, int? Offset) : IRequest<IEnumerable<BreweryDto>>;

web/backend/Features/Features.Breweries/Queries/GetAllBreweryLocations/GetAllBreweryLocationsHandler.cs

@@ -5,11 +5,15 @@ using MediatR;
 
 namespace Features.Breweries.Queries.GetAllBreweryLocations;
 
-/// <summary>Handles <see cref="GetAllBreweryLocationsQuery" /> by retrieving all located brewery posts.</summary>
+/// <summary>
+///     Handles queries for brewery posts with locations.
+/// </summary>
 public class GetAllBreweryLocationsHandler(IBreweryRepository repository)
     : IRequestHandler<GetAllBreweryLocationsQuery, IEnumerable<BreweryWithLocationDto>>
 {
-    /// <summary>Retrieves every brewery post that has a set location.</summary>
+    /// <summary>
+    ///     Retrieves and maps every brewery post that has a location.
+    /// </summary>
     public async Task<IEnumerable<BreweryWithLocationDto>> Handle(
         GetAllBreweryLocationsQuery request,
         CancellationToken cancellationToken

web/backend/Features/Features.Breweries/Queries/GetAllBreweryLocations/GetAllBreweryLocationsQuery.cs

@@ -4,7 +4,6 @@ using MediatR;
 namespace Features.Breweries.Queries.GetAllBreweryLocations;
 
 /// <summary>
-///     Retrieves all brewery posts that have a set location. Bound directly from
-///     <c>GET /api/brewery/locations</c>.
+///     Requests brewery posts that include a location.
 /// </summary>
 public record GetAllBreweryLocationsQuery : IRequest<IEnumerable<BreweryWithLocationDto>>;

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

@@ -5,17 +5,24 @@ using MediatR;
 
 namespace Features.Breweries.Queries.GetBreweryById;
 
-/// <summary>Handles <see cref="GetBreweryByIdQuery" /> by retrieving the matching brewery post.</summary>
+/// <summary>
+///     Handles lookup requests for individual brewery posts.
+/// </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>
+    /// <summary>
+    ///     Retrieves and maps the post, if it exists.
+    /// </summary>
     public async Task<BreweryDto?> Handle(
         GetBreweryByIdQuery request,
         CancellationToken cancellationToken
     )
     {
-        BreweryPost? brewery = await repository.GetByIdAsync(request.BreweryPostId, cancellationToken);
+        BreweryPost? brewery = await repository.GetByIdAsync(
+            request.BreweryPostId,
+            cancellationToken
+        );
         return brewery?.ToDto();
     }
 }

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

@@ -3,6 +3,10 @@ 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>
+/// <summary>
+///     Requests a brewery post by its identifier.
+/// </summary>
+/// <remarks>
+///     The handler returns <see langword="null" /> when the post is absent.
+/// </remarks>
 public record GetBreweryByIdQuery(Guid BreweryPostId) : IRequest<BreweryDto?>;

web/backend/Features/Features.Breweries/Queries/GetBreweryLocationsWithinRange/GetBreweryLocationsWithinRangeHandler.cs

@@ -6,12 +6,14 @@ using MediatR;
 namespace Features.Breweries.Queries.GetBreweryLocationsWithinRange;
 
 /// <summary>
-///     Handles <see cref="GetBreweryLocationsWithinRangeQuery" /> by retrieving nearby located brewery posts.
+///     Handles proximity searches for brewery locations.
 /// </summary>
 public class GetBreweryLocationsWithinRangeHandler(IBreweryRepository repository)
     : IRequestHandler<GetBreweryLocationsWithinRangeQuery, IEnumerable<BreweryWithLocationDto>>
 {
-    /// <summary>Retrieves brewery posts within range of the requested coordinates, nearest first.</summary>
+    /// <summary>
+    ///     Retrieves and maps nearby brewery locations.
+    /// </summary>
     public async Task<IEnumerable<BreweryWithLocationDto>> Handle(
         GetBreweryLocationsWithinRangeQuery request,
         CancellationToken cancellationToken

web/backend/Features/Features.Breweries/Queries/GetBreweryLocationsWithinRange/GetBreweryLocationsWithinRangeQuery.cs

@@ -4,12 +4,19 @@ using MediatR;
 namespace Features.Breweries.Queries.GetBreweryLocationsWithinRange;
 
 /// <summary>
-///     Retrieves brewery posts with a set location within <paramref name="RangeInMetres" /> of the given
-///     coordinates, nearest first. Bound directly from the query string of
-///     <c>GET /api/brewery/locations/nearby</c>.
+///     Requests located brewery posts near a geographic point, nearest first.
 /// </summary>
-/// <param name="Latitude">The origin latitude, in decimal degrees.</param>
-/// <param name="Longitude">The origin longitude, in decimal degrees.</param>
-/// <param name="RangeInMetres">The maximum distance, in metres, from the origin coordinates.</param>
-public record GetBreweryLocationsWithinRangeQuery(double Latitude, double Longitude, double RangeInMetres)
-    : IRequest<IEnumerable<BreweryWithLocationDto>>;
+/// <param name="Latitude">
+///     Sets the origin latitude in decimal degrees.
+/// </param>
+/// <param name="Longitude">
+///     Sets the origin longitude in decimal degrees.
+/// </param>
+/// <param name="RangeInMetres">
+///     Sets the inclusive search radius in metres.
+/// </param>
+public record GetBreweryLocationsWithinRangeQuery(
+    double Latitude,
+    double Longitude,
+    double RangeInMetres
+) : IRequest<IEnumerable<BreweryWithLocationDto>>;

web/backend/Features/Features.Breweries/Queries/GetBreweryLocationsWithinRange/GetBreweryLocationsWithinRangeValidator.cs

@@ -2,7 +2,9 @@ using FluentValidation;
 
 namespace Features.Breweries.Queries.GetBreweryLocationsWithinRange;
 
-/// <summary>Validates <see cref="GetBreweryLocationsWithinRangeQuery" />.</summary>
+/// <summary>
+///     Validates coordinates and radius values for proximity searches.
+/// </summary>
 public class GetBreweryLocationsWithinRangeValidator
     : AbstractValidator<GetBreweryLocationsWithinRangeQuery>
 {