docs: add XML documentation to utilities and configurations

Author: nanotaboada

src/Dotnet.Samples.AspNetCore.WebApi/Configurations/AuthorizeCheckOperationFilter.cs

@@ -10,6 +10,11 @@ namespace Dotnet.Samples.AspNetCore.WebApi.Configurations
     /// </summary>
     public class AuthorizeCheckOperationFilter : IOperationFilter
     {
+        /// <summary>
+        /// Applies the Bearer security requirement to Swagger operations with [Authorize] attributes.
+        /// </summary>
+        /// <param name="operation">The OpenAPI operation to modify.</param>
+        /// <param name="context">The operation filter context containing method metadata.</param>
         public void Apply(OpenApiOperation operation, OperationFilterContext context)
         {
             // Check if [Authorize] is applied at the method or class level

src/Dotnet.Samples.AspNetCore.WebApi/Utilities/PlayerData.cs

@@ -4,8 +4,17 @@
 
 namespace Dotnet.Samples.AspNetCore.WebApi.Utilities;
 
+/// <summary>
+/// Provides static player data for database seeding and testing.
+/// Single source of truth for all player definitions.
+/// </summary>
 public static class PlayerData
 {
+    /// <summary>
+    /// Returns the starting 11 players without IDs (for EF Core auto-increment).
+    /// Used for database migrations and seeding.
+    /// </summary>
+    /// <returns>List of 11 Player entities representing the starting lineup.</returns>
     public static List<Player> MakeStarting11()
     {
         return

test/Dotnet.Samples.AspNetCore.WebApi.Tests/Utilities/DatabaseFakes.cs

@@ -14,6 +14,11 @@ namespace Dotnet.Samples.AspNetCore.WebApi.Tests.Utilities
     /// </summary>
     public static class DatabaseFakes
     {
+        /// <summary>
+        /// Creates an in-memory SQLite connection and DbContext options for testing.
+        /// The connection remains open for the lifetime of the test.
+        /// </summary>
+        /// <returns>A tuple containing the SQLite connection and DbContext options.</returns>
         public static (DbConnection, DbContextOptions<PlayerDbContext>) CreateSqliteConnection()
         {
             var dbConnection = new SqliteConnection("Filename=:memory:");
@@ -26,13 +31,23 @@ public static (DbConnection, DbContextOptions<PlayerDbContext>) CreateSqliteConn
             return (dbConnection, dbContextOptions);
         }
 
+        /// <summary>
+        /// Creates a PlayerDbContext instance with the specified options.
+        /// </summary>
+        /// <param name="dbContextOptions">The DbContext options to use.</param>
+        /// <returns>A new PlayerDbContext instance.</returns>
         public static PlayerDbContext CreateDbContext(
             DbContextOptions<PlayerDbContext> dbContextOptions
         )
         {
             return new PlayerDbContext(dbContextOptions);
         }
 
+        /// <summary>
+        /// Creates the database schema for the test database.
+        /// Extension method for PlayerDbContext.
+        /// </summary>
+        /// <param name="context">The PlayerDbContext instance.</param>
         public static void CreateTable(this PlayerDbContext context)
         {
             using var cmd = context.Database.GetDbConnection().CreateCommand();
@@ -46,6 +61,11 @@ CREATE TABLE players (
             cmd.ExecuteNonQuery();
         }
 
+        /// <summary>
+        /// Seeds the test database with the starting 11 players.
+        /// Extension method for PlayerDbContext.
+        /// </summary>
+        /// <param name="context">The PlayerDbContext instance.</param>
         public static void Seed(this PlayerDbContext context)
         {
             context.Players.AddRange(PlayerFakes.MakeStarting11());

test/Dotnet.Samples.AspNetCore.WebApi.Tests/Utilities/PlayerFakes.cs

@@ -68,6 +68,10 @@ public static Player MakeNew()
      * Create
      * ---------------------------------------------------------------------- */
 
+    /// <summary>
+    /// Creates a PlayerRequestModel for testing create operations.
+    /// Uses data from a substitute player (Leandro Paredes).
+    /// </summary>
     public static PlayerRequestModel MakeRequestModelForCreate()
     {
         var player = MakeNew();
@@ -85,6 +89,10 @@ public static PlayerRequestModel MakeRequestModelForCreate()
         };
     }
 
+    /// <summary>
+    /// Creates a PlayerResponseModel for testing create operation responses.
+    /// Uses data from a substitute player (Leandro Paredes).
+    /// </summary>
     public static PlayerResponseModel MakeResponseModelForCreate()
     {
         var player = MakeNew();
@@ -106,6 +114,11 @@ public static PlayerResponseModel MakeResponseModelForCreate()
      * Retrieve
      * ---------------------------------------------------------------------- */
 
+    /// <summary>
+    /// Creates a PlayerRequestModel for testing retrieve operations.
+    /// Uses data from the starting 11 based on the specified squad number.
+    /// </summary>
+    /// <param name="squadNumber">The squad number of the player to retrieve.</param>
     public static PlayerRequestModel MakeRequestModelForRetrieve(int squadNumber)
     {
         var player =
@@ -127,6 +140,11 @@ public static PlayerRequestModel MakeRequestModelForRetrieve(int squadNumber)
         };
     }
 
+    /// <summary>
+    /// Creates a PlayerResponseModel for testing retrieve operation responses.
+    /// Uses data from the starting 11 based on the specified squad number.
+    /// </summary>
+    /// <param name="squadNumber">The squad number of the player to retrieve.</param>
     public static PlayerResponseModel MakeResponseModelForRetrieve(int squadNumber)
     {
         var player =
@@ -148,6 +166,10 @@ public static PlayerResponseModel MakeResponseModelForRetrieve(int squadNumber)
         };
     }
 
+    /// <summary>
+    /// Creates a list of PlayerResponseModel for testing retrieve all operations.
+    /// Uses all players from the starting 11.
+    /// </summary>
     public static List<PlayerResponseModel> MakeResponseModelsForRetrieve() =>
         [
             .. PlayerData
@@ -173,11 +195,21 @@ .. PlayerData
      * Update
      * ---------------------------------------------------------------------- */
 
+    /// <summary>
+    /// Creates a PlayerRequestModel for testing update operations.
+    /// Delegates to MakeRequestModelForRetrieve.
+    /// </summary>
+    /// <param name="squadNumber">The squad number of the player to update.</param>
     public static PlayerRequestModel MakeRequestModelForUpdate(int squadNumber)
     {
         return MakeRequestModelForRetrieve(squadNumber);
     }
 
+    /// <summary>
+    /// Creates a PlayerResponseModel for testing update operation responses.
+    /// Delegates to MakeResponseModelForRetrieve.
+    /// </summary>
+    /// <param name="squadNumber">The squad number of the player to update.</param>
     public static PlayerResponseModel MakeResponseModelForUpdate(int squadNumber)
     {
         return MakeResponseModelForRetrieve(squadNumber);

test/Dotnet.Samples.AspNetCore.WebApi.Tests/Utilities/PlayerMocks.cs

@@ -22,6 +22,10 @@ namespace Dotnet.Samples.AspNetCore.WebApi.Tests.Utilities
     /// </summary>
     public static class PlayerMocks
     {
+        /// <summary>
+        /// Initializes mocks for PlayerController dependencies.
+        /// </summary>
+        /// <returns>A tuple containing mocked service, logger, and validator.</returns>
         public static (
             Mock<IPlayerService> service,
             Mock<ILogger<PlayerController>> logger,
@@ -35,6 +39,10 @@ Mock<IValidator<PlayerRequestModel>> validator
             return (service, logger, validator);
         }
 
+        /// <summary>
+        /// Creates a mock IUrlHelper configured to return any string for Action calls.
+        /// </summary>
+        /// <returns>A configured Mock of IUrlHelper.</returns>
         public static Mock<IUrlHelper> SetupUrlHelperMock()
         {
             var mock = new Mock<IUrlHelper>();
@@ -43,6 +51,12 @@ public static Mock<IUrlHelper> SetupUrlHelperMock()
             return mock;
         }
 
+        /// <summary>
+        /// Initializes mocks for PlayerService dependencies.
+        /// </summary>
+        /// <param name="cacheValue">Optional cache value to return from memory cache.</param>
+        /// <param name="environmentName">The environment name (defaults to "Development").</param>
+        /// <returns>A tuple containing mocked repository, logger, cache, mapper, and environment.</returns>
         public static (
             Mock<IPlayerRepository> repository,
             Mock<ILogger<PlayerService>> logger,
@@ -60,6 +74,12 @@ Mock<IHostEnvironment> environment
             return (repository, logger, memoryCache, mapper, environment);
         }
 
+        /// <summary>
+        /// Creates a mock IMemoryCache with configurable behavior.
+        /// First TryGetValue call returns false, subsequent calls return true with the specified value.
+        /// </summary>
+        /// <param name="value">The value to return from cache after the first call.</param>
+        /// <returns>A configured Mock of IMemoryCache.</returns>
         public static Mock<IMemoryCache> SetupMemoryCacheMock(object? value)
         {
             var cachedValue = false;

test/Dotnet.Samples.AspNetCore.WebApi.Tests/Utilities/PlayerStubs.cs

@@ -14,6 +14,13 @@ namespace Dotnet.Samples.AspNetCore.WebApi.Tests.Utilities
     /// </summary>
     public static class PlayerStubs
     {
+        /// <summary>
+        /// Creates a ModelStateDictionary with a single validation error.
+        /// Used for testing validation failure scenarios.
+        /// </summary>
+        /// <param name="key">The property name or key for the error.</param>
+        /// <param name="errorMessage">The error message.</param>
+        /// <returns>A ModelStateDictionary containing the specified error.</returns>
         public static ModelStateDictionary CreateModelError(string key, string errorMessage)
         {
             var modelStateDictionary = new ModelStateDictionary();