add xmldoc comments

web/backend/API/API.Core/Controllers/AuthController.cs

@@ -7,6 +7,17 @@ using Service.Auth;
 
 namespace API.Core.Controllers
 {
+    /// <summary>
+    /// Handles user authentication concerns: registration, login, email confirmation, and token refresh.
+    /// </summary>
+    /// <remarks>
+    /// The controller is decorated with <c>[Authorize(AuthenticationSchemes = "JWT")]</c> by default, but most
+    /// actions opt out via <c>[AllowAnonymous]</c> since they are entry points used before a caller holds a token.
+    /// </remarks>
+    /// <param name="registerService">Service used to register new user accounts.</param>
+    /// <param name="loginService">Service used to authenticate existing user accounts.</param>
+    /// <param name="confirmationService">Service used to confirm user accounts and resend confirmation emails.</param>
+    /// <param name="tokenService">Service used to refresh JWT access/refresh token pairs.</param>
     [ApiController]
     [Route("api/[controller]")]
     [Authorize(AuthenticationSchemes = "JWT")]
@@ -17,6 +28,15 @@ namespace API.Core.Controllers
         ITokenService tokenService
     ) : ControllerBase
     {
+        /// <summary>
+        /// Registers a new user account.
+        /// </summary>
+        /// <remarks>
+        /// Allows anonymous access. On success, responds with <c>201 Created</c> containing the new user's ID,
+        /// username, issued refresh/access tokens, and whether a confirmation email was sent.
+        /// </remarks>
+        /// <param name="req">The registration details, including username, name, email, date of birth, and password.</param>
+        /// <returns>A <c>201 Created</c> result wrapping a <see cref="ResponseBody{T}"/> of <see cref="RegistrationPayload"/>.</returns>
         [AllowAnonymous]
         [HttpPost("register")]
         public async Task<ActionResult<UserAccount>> Register(
@@ -50,6 +70,15 @@ namespace API.Core.Controllers
             return Created("/", response);
         }
 
+        /// <summary>
+        /// Authenticates a user with a username and password.
+        /// </summary>
+        /// <remarks>
+        /// Allows anonymous access. On success, responds with <c>200 OK</c> containing the user's ID,
+        /// username, and a newly issued refresh/access token pair.
+        /// </remarks>
+        /// <param name="req">The login credentials (username and password).</param>
+        /// <returns>An <c>200 OK</c> result wrapping a <see cref="ResponseBody{T}"/> of <see cref="LoginPayload"/>.</returns>
         [AllowAnonymous]
         [HttpPost("login")]
         public async Task<ActionResult> Login([FromBody] LoginRequest req)
@@ -70,6 +99,15 @@ namespace API.Core.Controllers
             );
         }
 
+        /// <summary>
+        /// Confirms a user account using a confirmation token.
+        /// </summary>
+        /// <remarks>
+        /// Requires JWT authentication. On success, responds with <c>200 OK</c> containing the confirmed
+        /// user's ID and the confirmation timestamp.
+        /// </remarks>
+        /// <param name="token">The confirmation token supplied via the confirmation email link.</param>
+        /// <returns>A <c>200 OK</c> result wrapping a <see cref="ResponseBody{T}"/> of <see cref="ConfirmationPayload"/>.</returns>
         [HttpPost("confirm")]
         public async Task<ActionResult> Confirm([FromQuery] string token)
         {
@@ -86,6 +124,14 @@ namespace API.Core.Controllers
             );
         }
 
+        /// <summary>
+        /// Resends the account confirmation email for the specified user.
+        /// </summary>
+        /// <remarks>
+        /// Requires JWT authentication. On success, responds with <c>200 OK</c>.
+        /// </remarks>
+        /// <param name="userId">The unique identifier of the user account to resend the confirmation email for.</param>
+        /// <returns>A <c>200 OK</c> result wrapping a <see cref="ResponseBody"/> confirming the email was resent.</returns>
         [HttpPost("confirm/resend")]
         public async Task<ActionResult> ResendConfirmation([FromQuery] Guid userId)
         {
@@ -93,6 +139,15 @@ namespace API.Core.Controllers
             return Ok(new ResponseBody { Message = "confirmation email has been resent" });
         }
 
+        /// <summary>
+        /// Exchanges a valid refresh token for a new access/refresh token pair.
+        /// </summary>
+        /// <remarks>
+        /// Allows anonymous access. On success, responds with <c>200 OK</c> containing the user's ID,
+        /// username, and the newly issued refresh/access token pair.
+        /// </remarks>
+        /// <param name="req">The request containing the refresh token to exchange.</param>
+        /// <returns>A <c>200 OK</c> result wrapping a <see cref="ResponseBody{T}"/> of <see cref="LoginPayload"/>.</returns>
         [AllowAnonymous]
         [HttpPost("refresh")]
         public async Task<ActionResult> Refresh(

web/backend/API/API.Core/Controllers/BreweryController.cs

@@ -1,16 +1,34 @@
 using API.Core.Contracts.Breweries;
 using API.Core.Contracts.Common;
+using Domain.Entities;
 using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Mvc;
 using Service.Breweries;
 
 namespace API.Core.Controllers;
 
+/// <summary>
+/// Provides CRUD endpoints for managing brewery posts.
+/// </summary>
+/// <remarks>
+/// The controller is decorated with <c>[Authorize(AuthenticationSchemes = "JWT")]</c> by default; read endpoints
+/// (<see cref="GetById"/> and <see cref="GetAll"/>) opt out via <c>[AllowAnonymous]</c>.
+/// </remarks>
+/// <param name="breweryService">Service used to query and mutate brewery post data.</param>
 [ApiController]
 [Route("api/[controller]")]
 [Authorize(AuthenticationSchemes = "JWT")]
 public class BreweryController(IBreweryService breweryService) : ControllerBase
 {
+    /// <summary>
+    /// Retrieves a single brewery post by its unique identifier.
+    /// </summary>
+    /// <remarks>Allows anonymous access.</remarks>
+    /// <param name="id">The unique identifier of the brewery post to retrieve.</param>
+    /// <returns>
+    /// A <c>200 OK</c> result wrapping a <see cref="ResponseBody{T}"/> of <see cref="BreweryDto"/> if found;
+    /// otherwise a <c>404 Not Found</c> result wrapping a <see cref="ResponseBody"/> error message.
+    /// </returns>
     [AllowAnonymous]
     [HttpGet("{id:guid}")]
     public async Task<ActionResult<ResponseBody<BreweryDto>>> GetById(Guid id)
@@ -26,6 +44,13 @@ public class BreweryController(IBreweryService breweryService) : ControllerBase
         });
     }
 
+    /// <summary>
+    /// Retrieves a paginated list of brewery posts.
+    /// </summary>
+    /// <remarks>Allows anonymous access.</remarks>
+    /// <param name="limit">The maximum number of brewery posts to return, or <c>null</c> for no limit.</param>
+    /// <param name="offset">The number of brewery posts to skip before returning results, or <c>null</c> for no offset.</param>
+    /// <returns>A <c>200 OK</c> result wrapping a <see cref="ResponseBody{T}"/> of a collection of <see cref="BreweryDto"/>.</returns>
     [AllowAnonymous]
     [HttpGet]
     public async Task<ActionResult<ResponseBody<IEnumerable<BreweryDto>>>> GetAll(
@@ -40,6 +65,14 @@ public class BreweryController(IBreweryService breweryService) : ControllerBase
         });
     }
 
+    /// <summary>
+    /// Creates a new brewery post.
+    /// </summary>
+    /// <param name="dto">The brewery details to create, including the posting user, name, description, and location.</param>
+    /// <returns>
+    /// A <c>201 Created</c> result wrapping a <see cref="ResponseBody{T}"/> of the newly created <see cref="BreweryDto"/>
+    /// if creation succeeds; otherwise a <c>400 Bad Request</c> result wrapping a <see cref="ResponseBody"/> error message.
+    /// </returns>
     [HttpPost]
     public async Task<ActionResult<ResponseBody<BreweryDto>>> Create([FromBody] BreweryCreateDto dto)
     {
@@ -67,6 +100,16 @@ public class BreweryController(IBreweryService breweryService) : ControllerBase
         });
     }
 
+    /// <summary>
+    /// Updates an existing brewery post.
+    /// </summary>
+    /// <param name="id">The unique identifier of the brewery post from the route, which must match <paramref name="dto"/>'s ID.</param>
+    /// <param name="dto">The updated brewery details, including the posting user, name, description, and optional location.</param>
+    /// <returns>
+    /// A <c>200 OK</c> result wrapping a <see cref="ResponseBody{T}"/> of the updated brewery (as a <see cref="BreweryPost"/>)
+    /// if the update succeeds; otherwise a <c>400 Bad Request</c> result wrapping a <see cref="ResponseBody"/> error message
+    /// (returned when the route ID does not match the payload ID, or when the update itself fails).
+    /// </returns>
     [HttpPut("{id:guid}")]
     public async Task<ActionResult<ResponseBody<BreweryDto>>> Update(Guid id, [FromBody] BreweryDto dto)
     {
@@ -92,13 +135,18 @@ public class BreweryController(IBreweryService breweryService) : ControllerBase
         if (!result.Success)
             return BadRequest(new ResponseBody { Message = result.Message });
 
-        return Ok(new ResponseBody<BreweryDto>
+        return Ok(new ResponseBody<BreweryPost>
         {
             Message = "Brewery updated successfully.",
-            Payload = MapToDto(result.Brewery),
+            Payload = result.Brewery,
         });
     }
 
+    /// <summary>
+    /// Deletes a brewery post.
+    /// </summary>
+    /// <param name="id">The unique identifier of the brewery post to delete.</param>
+    /// <returns>A <c>200 OK</c> result wrapping a <see cref="ResponseBody"/> confirming the deletion.</returns>
     [HttpDelete("{id:guid}")]
     public async Task<ActionResult<ResponseBody>> Delete(Guid id)
     {
@@ -106,7 +154,13 @@ public class BreweryController(IBreweryService breweryService) : ControllerBase
         return Ok(new ResponseBody { Message = "Brewery deleted successfully." });
     }
 
-    private static BreweryDto MapToDto(Domain.Entities.BreweryPost b) => new()
+    /// <summary>
+    /// Maps a <see cref="BreweryPost"/> domain entity to its <see cref="BreweryDto"/> representation,
+    /// including its location, if present.
+    /// </summary>
+    /// <param name="b">The brewery post entity to map.</param>
+    /// <returns>The mapped <see cref="BreweryDto"/>.</returns>
+    private static BreweryDto MapToDto(BreweryPost b) => new()
     {
         BreweryPostId = b.BreweryPostId,
         PostedById = b.PostedById,

web/backend/API/API.Core/Controllers/NotFoundController.cs

@@ -2,11 +2,22 @@ using Microsoft.AspNetCore.Mvc;
 
 namespace API.Core.Controllers
 {
+    /// <summary>
+    /// Handles requests that do not match any other route, used as the application's fallback controller.
+    /// </summary>
+    /// <remarks>
+    /// Excluded from API explorer/Swagger output via <c>[ApiExplorerSettings(IgnoreApi = true)]</c>.
+    /// Wired up as the fallback target via <c>app.MapFallbackToController("Handle404", "NotFound")</c> in <c>Program.cs</c>.
+    /// </remarks>
     [ApiController]
     [ApiExplorerSettings(IgnoreApi = true)]
     [Route("error")] // required
     public class NotFoundController : ControllerBase
     {
+        /// <summary>
+        /// Returns a generic 404 response for any request that did not match a defined route.
+        /// </summary>
+        /// <returns>A <c>404 Not Found</c> result with a JSON body containing a "Route not found." message.</returns>
         [HttpGet("404")] //required
         public IActionResult Handle404()
         {

web/backend/API/API.Core/Controllers/ProtectedController.cs

@@ -5,11 +5,22 @@ using Microsoft.AspNetCore.Mvc;
 
 namespace API.Core.Controllers;
 
+/// <summary>
+/// Sample controller demonstrating an endpoint that requires JWT authentication.
+/// </summary>
 [ApiController]
 [Route("api/[controller]")]
 [Authorize(AuthenticationSchemes = "JWT")]
 public class ProtectedController : ControllerBase
 {
+    /// <summary>
+    /// Returns the authenticated caller's user ID and username, extracted from the JWT claims.
+    /// </summary>
+    /// <returns>
+    /// A <c>200 OK</c> result wrapping a <see cref="ResponseBody{T}"/> whose payload contains the
+    /// caller's <c>userId</c> (from <see cref="ClaimTypes.NameIdentifier"/>) and <c>username</c>
+    /// (from <see cref="ClaimTypes.Name"/>), either of which may be <c>null</c> if not present in the token.
+    /// </returns>
     [HttpGet]
     public ActionResult<ResponseBody<object>> Get()
     {

web/backend/API/API.Core/Controllers/UserController.cs

@@ -4,10 +4,20 @@ using Service.UserManagement.User;
 
 namespace API.Core.Controllers
 {
+    /// <summary>
+    /// Provides read-only endpoints for retrieving user accounts.
+    /// </summary>
+    /// <param name="userService">Service used to query user account data.</param>
     [ApiController]
     [Route("api/[controller]")]
     public class UserController(IUserService userService) : ControllerBase
     {
+        /// <summary>
+        /// Retrieves a paginated list of user accounts.
+        /// </summary>
+        /// <param name="limit">The maximum number of user accounts to return, or <c>null</c> for no limit.</param>
+        /// <param name="offset">The number of user accounts to skip before returning results, or <c>null</c> for no offset.</param>
+        /// <returns>A <c>200 OK</c> result containing the collection of <see cref="UserAccount"/> entities.</returns>
         [HttpGet]
         public async Task<ActionResult<IEnumerable<UserAccount>>> GetAll(
             [FromQuery] int? limit,
@@ -18,6 +28,11 @@ namespace API.Core.Controllers
             return Ok(users);
         }
 
+        /// <summary>
+        /// Retrieves a single user account by its unique identifier.
+        /// </summary>
+        /// <param name="id">The unique identifier of the user account to retrieve.</param>
+        /// <returns>A <c>200 OK</c> result containing the matching <see cref="UserAccount"/>.</returns>
         [HttpGet("{id:guid}")]
         public async Task<ActionResult<UserAccount>> GetById(Guid id)
         {