add xmldoc comments

web/backend/API/API.Core/Contracts/Auth/AuthDTO.cs

@@ -3,6 +3,13 @@ using Org.BouncyCastle.Asn1.Cms;
 
 namespace API.Core.Contracts.Auth;
 
+/// <summary>
+/// Payload returned to the client after a successful login or token refresh.
+/// </summary>
+/// <param name="UserAccountId">The unique identifier of the authenticated user account.</param>
+/// <param name="Username">The username of the authenticated user account.</param>
+/// <param name="RefreshToken">The newly issued refresh token used to obtain new access tokens.</param>
+/// <param name="AccessToken">The newly issued JWT access token used to authorize subsequent requests.</param>
 public record LoginPayload(
     Guid UserAccountId,
     string Username,
@@ -10,6 +17,14 @@ public record LoginPayload(
     string AccessToken
 );
 
+/// <summary>
+/// Payload returned to the client after a successful registration.
+/// </summary>
+/// <param name="UserAccountId">The unique identifier of the newly created user account.</param>
+/// <param name="Username">The username of the newly created user account.</param>
+/// <param name="RefreshToken">The refresh token issued for the new account.</param>
+/// <param name="AccessToken">The JWT access token issued for the new account.</param>
+/// <param name="ConfirmationEmailSent">Whether a confirmation email was successfully sent to the new user.</param>
 public record RegistrationPayload(
     Guid UserAccountId,
     string Username,
@@ -18,4 +33,9 @@ public record RegistrationPayload(
     bool ConfirmationEmailSent
 );
 
+/// <summary>
+/// Payload returned to the client after a user account's email has been confirmed.
+/// </summary>
+/// <param name="UserAccountId">The unique identifier of the user account that was confirmed.</param>
+/// <param name="ConfirmedDate">The date and time at which the account was confirmed.</param>
 public record ConfirmationPayload(Guid UserAccountId, DateTime ConfirmedDate);

web/backend/API/API.Core/Contracts/Auth/Login.cs

@@ -3,14 +3,31 @@ using FluentValidation;
 
 namespace API.Core.Contracts.Auth;
 
+/// <summary>
+/// Request body for the login endpoint, containing the credentials used to authenticate a user.
+/// </summary>
 public record LoginRequest
 {
+    /// <summary>
+    /// The username of the account attempting to log in.
+    /// </summary>
     public string Username { get; init; } = default!;
+
+    /// <summary>
+    /// The plaintext password of the account attempting to log in.
+    /// </summary>
     public string Password { get; init; } = default!;
 }
 
+/// <summary>
+/// Validates <see cref="LoginRequest"/> instances before they are processed by the login endpoint.
+/// </summary>
 public class LoginRequestValidator : AbstractValidator<LoginRequest>
 {
+    /// <summary>
+    /// Configures validation rules requiring both <see cref="LoginRequest.Username"/> and
+    /// <see cref="LoginRequest.Password"/> to be non-empty.
+    /// </summary>
     public LoginRequestValidator()
     {
         RuleFor(x => x.Username).NotEmpty().WithMessage("Username is required");

web/backend/API/API.Core/Contracts/Auth/RefreshToken.cs

@@ -2,14 +2,26 @@ using FluentValidation;
 
 namespace API.Core.Contracts.Auth;
 
+/// <summary>
+/// Request body for the token refresh endpoint, containing the refresh token used to obtain a new access token.
+/// </summary>
 public record RefreshTokenRequest
 {
+    /// <summary>
+    /// The refresh token previously issued to the client during login, registration, or a prior refresh.
+    /// </summary>
     public string RefreshToken { get; init; } = default!;
 }
 
+/// <summary>
+/// Validates <see cref="RefreshTokenRequest"/> instances before they are processed by the refresh endpoint.
+/// </summary>
 public class RefreshTokenRequestValidator
     : AbstractValidator<RefreshTokenRequest>
 {
+    /// <summary>
+    /// Configures a validation rule requiring <see cref="RefreshTokenRequest.RefreshToken"/> to be non-empty.
+    /// </summary>
     public RefreshTokenRequestValidator()
     {
         RuleFor(x => x.RefreshToken)

web/backend/API/API.Core/Contracts/Auth/Register.cs

@@ -3,6 +3,15 @@ using FluentValidation;
 
 namespace API.Core.Contracts.Auth;
 
+/// <summary>
+/// Request body for the registration endpoint, containing the details needed to create a new user account.
+/// </summary>
+/// <param name="Username">The desired username; must be 3-64 characters and contain only letters, numbers, dots, underscores, and hyphens.</param>
+/// <param name="FirstName">The user's first name; up to 128 characters.</param>
+/// <param name="LastName">The user's last name; up to 128 characters.</param>
+/// <param name="Email">The user's email address; up to 128 characters and must be a valid email format.</param>
+/// <param name="DateOfBirth">The user's date of birth; the user must be at least 19 years old.</param>
+/// <param name="Password">The desired plaintext password; must be at least 8 characters and contain an uppercase letter, a lowercase letter, a number, and a special character.</param>
 public record RegisterRequest(
     string Username,
     string FirstName,
@@ -12,8 +21,15 @@ public record RegisterRequest(
     string Password
 );
 
+/// <summary>
+/// Validates <see cref="RegisterRequest"/> instances before they are processed by the registration endpoint.
+/// </summary>
 public class RegisterRequestValidator : AbstractValidator<RegisterRequest>
 {
+    /// <summary>
+    /// Configures validation rules for username format and length, first/last name length, email format and
+    /// length, minimum age based on date of birth, and password strength requirements.
+    /// </summary>
     public RegisterRequestValidator()
     {
         RuleFor(x => x.Username)

web/backend/API/API.Core/Contracts/Breweries/BreweryCreateRequestValidator.cs

@@ -2,8 +2,17 @@ using FluentValidation;
 
 namespace API.Core.Contracts.Breweries;
 
+/// <summary>
+/// Validates <see cref="BreweryCreateDto"/> instances before they are processed by the brewery creation endpoint.
+/// </summary>
 public class BreweryCreateDtoValidator : AbstractValidator<BreweryCreateDto>
 {
+    /// <summary>
+    /// Configures validation rules requiring <see cref="BreweryCreateDto.PostedById"/>,
+    /// <see cref="BreweryCreateDto.BreweryName"/>, <see cref="BreweryCreateDto.Description"/>, and
+    /// <see cref="BreweryCreateDto.Location"/> to be present, with length limits on the name, description,
+    /// address line 1, and postal code fields.
+    /// </summary>
     public BreweryCreateDtoValidator()
     {
         RuleFor(x => x.PostedById)

web/backend/API/API.Core/Contracts/Breweries/BreweryDto.cs

@@ -1,41 +1,147 @@
 namespace API.Core.Contracts.Breweries;
 
+/// <summary>
+/// Request payload describing the location of a brewery to be created, supplied as part of
+/// <see cref="BreweryCreateDto"/>.
+/// </summary>
 public class BreweryLocationCreateDto
 {
+    /// <summary>
+    /// The unique identifier of the city in which the brewery is located.
+    /// </summary>
     public Guid CityId { get; set; }
+
+    /// <summary>
+    /// The primary street address line of the brewery.
+    /// </summary>
     public string AddressLine1 { get; set; } = string.Empty;
+
+    /// <summary>
+    /// An optional secondary address line (e.g. suite or unit number).
+    /// </summary>
     public string? AddressLine2 { get; set; }
+
+    /// <summary>
+    /// The postal/ZIP code of the brewery's address.
+    /// </summary>
     public string PostalCode { get; set; } = string.Empty;
+
+    /// <summary>
+    /// The optional geographic coordinates of the brewery, in a raw binary representation.
+    /// </summary>
     public byte[]? Coordinates { get; set; }
 }
 
+/// <summary>
+/// Represents the location details of an existing brewery, as returned in <see cref="BreweryDto"/>.
+/// </summary>
 public class BreweryLocationDto
 {
+    /// <summary>
+    /// The unique identifier of the brewery's location record.
+    /// </summary>
     public Guid BreweryPostLocationId { get; set; }
+
+    /// <summary>
+    /// The unique identifier of the brewery post that this location belongs to.
+    /// </summary>
     public Guid BreweryPostId { get; set; }
+
+    /// <summary>
+    /// The unique identifier of the city in which the brewery is located.
+    /// </summary>
     public Guid CityId { get; set; }
+
+    /// <summary>
+    /// The primary street address line of the brewery.
+    /// </summary>
     public string AddressLine1 { get; set; } = string.Empty;
+
+    /// <summary>
+    /// An optional secondary address line (e.g. suite or unit number).
+    /// </summary>
     public string? AddressLine2 { get; set; }
+
+    /// <summary>
+    /// The postal/ZIP code of the brewery's address.
+    /// </summary>
     public string PostalCode { get; set; } = string.Empty;
+
+    /// <summary>
+    /// The optional geographic coordinates of the brewery, in a raw binary representation.
+    /// </summary>
     public byte[]? Coordinates { get; set; }
 }
 
+/// <summary>
+/// Request body used by <see cref="Controllers.BreweryController.Create"/> to create a new brewery post.
+/// </summary>
 public class BreweryCreateDto
 {
+    /// <summary>
+    /// The unique identifier of the user account that is creating the brewery post.
+    /// </summary>
     public Guid PostedById { get; set; }
+
+    /// <summary>
+    /// The name of the brewery; required and limited to 256 characters.
+    /// </summary>
     public string BreweryName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// A description of the brewery; required and limited to 512 characters.
+    /// </summary>
     public string Description { get; set; } = string.Empty;
+
+    /// <summary>
+    /// The location details of the brewery being created.
+    /// </summary>
     public BreweryLocationCreateDto Location { get; set; } = null!;
 }
 
+/// <summary>
+/// Represents a brewery post as returned by, or submitted to, the brewery endpoints, including its
+/// metadata and optional location.
+/// </summary>
 public class BreweryDto
 {
+    /// <summary>
+    /// The unique identifier of the brewery post.
+    /// </summary>
     public Guid BreweryPostId { get; set; }
+
+    /// <summary>
+    /// The unique identifier of the user account that created the brewery post.
+    /// </summary>
     public Guid PostedById { get; set; }
+
+    /// <summary>
+    /// The name of the brewery.
+    /// </summary>
     public string BreweryName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// A description of the brewery.
+    /// </summary>
     public string Description { get; set; } = string.Empty;
+
+    /// <summary>
+    /// The date and time at which the brewery post was created.
+    /// </summary>
     public DateTime CreatedAt { get; set; }
+
+    /// <summary>
+    /// The date and time at which the brewery post was last updated, or <c>null</c> if it has never been updated.
+    /// </summary>
     public DateTime? UpdatedAt { get; set; }
+
+    /// <summary>
+    /// A row-version/concurrency token used to detect conflicting concurrent updates to the brewery post.
+    /// </summary>
     public byte[]? Timer { get; set; }
+
+    /// <summary>
+    /// The location details of the brewery, or <c>null</c> if no location is associated with it.
+    /// </summary>
     public BreweryLocationDto? Location { get; set; }
 }

web/backend/API/API.Core/Contracts/Common/ResponseBody.cs

@@ -1,12 +1,29 @@
 namespace API.Core.Contracts.Common;
 
+/// <summary>
+/// Generic envelope used to wrap API responses that carry a data payload alongside a human-readable message.
+/// </summary>
+/// <typeparam name="T">The type of the data payload returned in the response.</typeparam>
 public record ResponseBody<T>
 {
+    /// <summary>
+    /// A human-readable message describing the outcome of the request.
+    /// </summary>
     public required string Message { get; init; }
+
+    /// <summary>
+    /// The data payload associated with the response.
+    /// </summary>
     public required T Payload { get; init; }
 }
 
+/// <summary>
+/// Envelope used to wrap API responses that carry only a human-readable message and no data payload.
+/// </summary>
 public record ResponseBody
 {
+    /// <summary>
+    /// A human-readable message describing the outcome of the request.
+    /// </summary>
     public required string Message { get; init; }
 }