add xmldoc comments

web/backend/Service/Service.Breweries/BreweryService.cs

@@ -3,14 +3,34 @@ using Infrastructure.Repository.Breweries;
 
 namespace Service.Breweries;
 
+/// <summary>
+/// Handles retrieval, creation, update, and deletion of brewery posts.
+/// </summary>
+/// <param name="repository">Repository used to persist and query brewery post data.</param>
 public class BreweryService(IBreweryRepository repository) : IBreweryService
 {
+    /// <summary>
+    /// Retrieves a brewery post by its unique identifier.
+    /// </summary>
+    /// <param name="id">The unique identifier of the brewery post.</param>
+    /// <returns>The matching <see cref="BreweryPost"/>, or <c>null</c> if no such post exists.</returns>
     public Task<BreweryPost?> GetByIdAsync(Guid id) =>
         repository.GetByIdAsync(id);
 
+    /// <summary>
+    /// Retrieves all brewery posts, optionally paginated.
+    /// </summary>
+    /// <param name="limit">The maximum number of results to return, or <c>null</c> for no limit.</param>
+    /// <param name="offset">The number of results to skip, or <c>null</c> to start from the beginning.</param>
+    /// <returns>A collection of <see cref="BreweryPost"/> entities.</returns>
     public Task<IEnumerable<BreweryPost>> GetAllAsync(int? limit = null, int? offset = null) =>
         repository.GetAllAsync(limit, offset);
 
+    /// <summary>
+    /// Creates a new brewery post, generating new identifiers for the post and its location.
+    /// </summary>
+    /// <param name="request">The details of the brewery post to create.</param>
+    /// <returns>A successful <see cref="BreweryServiceReturn"/> wrapping the newly created brewery post.</returns>
     public async Task<BreweryServiceReturn> CreateAsync(BreweryCreateRequest request)
     {
         var entity = new BreweryPost
@@ -35,6 +55,12 @@ public class BreweryService(IBreweryRepository repository) : IBreweryService
         return new BreweryServiceReturn(entity);
     }
 
+    /// <summary>
+    /// Updates an existing brewery post. If <paramref name="request"/> has no <c>Location</c>,
+    /// the brewery's location is cleared.
+    /// </summary>
+    /// <param name="request">The updated details of the brewery post.</param>
+    /// <returns>A successful <see cref="BreweryServiceReturn"/> wrapping the updated brewery post.</returns>
     public async Task<BreweryServiceReturn> UpdateAsync(BreweryUpdateRequest request)
     {
         var entity = new BreweryPost
@@ -60,6 +86,11 @@ public class BreweryService(IBreweryRepository repository) : IBreweryService
         return new BreweryServiceReturn(entity);
     }
 
+    /// <summary>
+    /// Deletes a brewery post by its unique identifier.
+    /// </summary>
+    /// <param name="id">The unique identifier of the brewery post to delete.</param>
+    /// <returns>A task that completes once the deletion has finished.</returns>
     public Task DeleteAsync(Guid id) =>
         repository.DeleteAsync(id);
 }

web/backend/Service/Service.Breweries/IBreweryService.cs

@@ -2,6 +2,13 @@ using Domain.Entities;
 
 namespace Service.Breweries;
 
+/// <summary>
+/// Represents the data required to create a new brewery post.
+/// </summary>
+/// <param name="PostedById">The unique identifier of the user creating the post.</param>
+/// <param name="BreweryName">The name of the brewery.</param>
+/// <param name="Description">A description of the brewery.</param>
+/// <param name="Location">The location details for the new brewery post.</param>
 public record BreweryCreateRequest(
     Guid PostedById,
     string BreweryName,
@@ -9,6 +16,14 @@ public record BreweryCreateRequest(
     BreweryLocationCreateRequest Location
 );
 
+/// <summary>
+/// Represents the location data required to create a new brewery post.
+/// </summary>
+/// <param name="CityId">The unique identifier of the city the brewery is located in.</param>
+/// <param name="AddressLine1">The primary address line.</param>
+/// <param name="AddressLine2">An optional secondary address line.</param>
+/// <param name="PostalCode">The postal code of the brewery's address.</param>
+/// <param name="Coordinates">Optional geographic coordinates for the brewery's location.</param>
 public record BreweryLocationCreateRequest(
     Guid CityId,
     string AddressLine1,
@@ -17,6 +32,14 @@ public record BreweryLocationCreateRequest(
     byte[]? Coordinates
 );
 
+/// <summary>
+/// Represents the data required to update an existing brewery post.
+/// </summary>
+/// <param name="BreweryPostId">The unique identifier of the brewery post to update.</param>
+/// <param name="PostedById">The unique identifier of the user who owns/posted the brewery.</param>
+/// <param name="BreweryName">The updated name of the brewery.</param>
+/// <param name="Description">The updated description of the brewery.</param>
+/// <param name="Location">The updated location details, or <c>null</c> to clear the location.</param>
 public record BreweryUpdateRequest(
     Guid BreweryPostId,
     Guid PostedById,
@@ -25,6 +48,15 @@ public record BreweryUpdateRequest(
     BreweryLocationUpdateRequest? Location
 );
 
+/// <summary>
+/// Represents the location data required to update an existing brewery post.
+/// </summary>
+/// <param name="BreweryPostLocationId">The unique identifier of the existing brewery location record.</param>
+/// <param name="CityId">The unique identifier of the city the brewery is located in.</param>
+/// <param name="AddressLine1">The primary address line.</param>
+/// <param name="AddressLine2">An optional secondary address line.</param>
+/// <param name="PostalCode">The postal code of the brewery's address.</param>
+/// <param name="Coordinates">Optional geographic coordinates for the brewery's location.</param>
 public record BreweryLocationUpdateRequest(
     Guid BreweryPostLocationId,
     Guid CityId,
@@ -34,18 +66,40 @@ public record BreweryLocationUpdateRequest(
     byte[]? Coordinates
 );
 
+/// <summary>
+/// Represents the result of a create or update operation against a brewery post.
+/// </summary>
 public record BreweryServiceReturn
 {
+    /// <summary>
+    /// Gets a value indicating whether the operation succeeded.
+    /// </summary>
     public bool Success { get; init; }
+
+    /// <summary>
+    /// Gets the resulting brewery post when the operation succeeded; otherwise a default/unset value.
+    /// </summary>
     public BreweryPost Brewery { get; init; }
+
+    /// <summary>
+    /// Gets a message describing the failure reason, empty when <see cref="Success"/> is <c>true</c>.
+    /// </summary>
     public string Message { get; init; } = string.Empty;
 
+    /// <summary>
+    /// Initializes a new successful result wrapping the given brewery post.
+    /// </summary>
+    /// <param name="brewery">The brewery post resulting from the operation.</param>
     public BreweryServiceReturn(BreweryPost brewery)
     {
         Success = true;
         Brewery = brewery;
     }
 
+    /// <summary>
+    /// Initializes a new failed result with the given error message.
+    /// </summary>
+    /// <param name="message">A message describing why the operation failed.</param>
     public BreweryServiceReturn(string message)
     {
         Success = false;
@@ -54,11 +108,44 @@ public record BreweryServiceReturn
     }
 }
 
+/// <summary>
+/// Defines operations for retrieving, creating, updating, and deleting brewery posts.
+/// </summary>
 public interface IBreweryService
 {
+    /// <summary>
+    /// Retrieves a brewery post by its unique identifier.
+    /// </summary>
+    /// <param name="id">The unique identifier of the brewery post.</param>
+    /// <returns>The matching <see cref="BreweryPost"/>, or <c>null</c> if no such post exists.</returns>
     Task<BreweryPost?> GetByIdAsync(Guid id);
+
+    /// <summary>
+    /// Retrieves all brewery posts, optionally paginated.
+    /// </summary>
+    /// <param name="limit">The maximum number of results to return, or <c>null</c> for no limit.</param>
+    /// <param name="offset">The number of results to skip, or <c>null</c> to start from the beginning.</param>
+    /// <returns>A collection of <see cref="BreweryPost"/> entities.</returns>
     Task<IEnumerable<BreweryPost>> GetAllAsync(int? limit = null, int? offset = null);
+
+    /// <summary>
+    /// Creates a new brewery post.
+    /// </summary>
+    /// <param name="request">The details of the brewery post to create.</param>
+    /// <returns>A <see cref="BreweryServiceReturn"/> describing the outcome of the creation.</returns>
     Task<BreweryServiceReturn> CreateAsync(BreweryCreateRequest request);
+
+    /// <summary>
+    /// Updates an existing brewery post.
+    /// </summary>
+    /// <param name="request">The updated details of the brewery post.</param>
+    /// <returns>A <see cref="BreweryServiceReturn"/> describing the outcome of the update.</returns>
     Task<BreweryServiceReturn> UpdateAsync(BreweryUpdateRequest request);
+
+    /// <summary>
+    /// Deletes a brewery post by its unique identifier.
+    /// </summary>
+    /// <param name="id">The unique identifier of the brewery post to delete.</param>
+    /// <returns>A task that completes once the deletion has finished.</returns>
     Task DeleteAsync(Guid id);
 }