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(