Add XML comments for improved code documentation

- Added detailed XML comments across services (`AuthService`, `ProjectService`, `JwtProvider`, `UserService`) and repositories (`ProjectRepository`).
- Introduced helper and test methods in `UserTest` and `ProjectTest` with comprehensive XML comments for clarity.
- Refactored and standardized XML comments for consistent structure and readability.

Author: SculptTechProject

sparkly-server.csproj

@@ -49,7 +49,6 @@
 
     <ItemGroup>
       <Compile Remove="sparkly-server.test\HealthzTest.cs" />
-      <Compile Remove="sparkly-server.test\TestWebAppliactionFactory.cs" />
       <Compile Remove="sparkly-server.test\UserTest.cs" />
     </ItemGroup>
 

sparkly-server.test/HealthzTest.cs

@@ -1,22 +1,22 @@
-using Sparkly.Tests.Infrastructure;
-using System.Net;
+using System.Net;
 
-namespace sparkly_server.Services.Users.test;
-
-public class HealthzTest : IClassFixture<TestWebApplicationFactory>
+namespace sparkly_server.test
 {
-    private readonly HttpClient _client;
-
-    public HealthzTest(TestWebApplicationFactory factory)
+    public class HealthzTest : IClassFixture<TestWebApplicationFactory>
     {
-        _client = factory.CreateClient();
-    }
+        private readonly HttpClient _client;
 
-    [Fact]
-    public async Task Healthz_ReturnsOk()
-    {
-        var response = await _client.GetAsync("/healthz");
+        public HealthzTest(TestWebApplicationFactory factory)
+        {
+            _client = factory.CreateClient();
+        }
+
+        [Fact]
+        public async Task Healthz_ReturnsOk()
+        {
+            var response = await _client.GetAsync("/healthz");
 
-        Assert.Equal(HttpStatusCode.OK, response.StatusCode);
+            Assert.Equal(HttpStatusCode.OK, response.StatusCode);
+        }
     }
 }

sparkly-server.test/ProjectTest.cs

@@ -0,0 +1,100 @@
+using Microsoft.Extensions.DependencyInjection;
+using sparkly_server.DTO.Auth;
+using sparkly_server.DTO.Projects;
+using sparkly_server.Enum;
+using sparkly_server.Infrastructure;
+using System.Net.Http.Headers;
+using System.Net.Http.Json;
+
+namespace sparkly_server.test
+{
+    public class ProjectTest : IClassFixture<TestWebApplicationFactory>, IAsyncLifetime
+    {
+        private readonly HttpClient _client;
+        private readonly TestWebApplicationFactory _factory;
+
+        public ProjectTest(TestWebApplicationFactory factory)
+        {
+            _factory = factory;
+            _client = factory.CreateClient();
+        }
+
+        public async Task InitializeAsync()
+        {
+            using var scope = _factory.Services.CreateScope();
+            var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
+
+            db.Users.RemoveRange(db.Users);
+            db.Projects.RemoveRange(db.Projects);
+            await db.SaveChangesAsync();
+        }
+
+        public Task DisposeAsync() => Task.CompletedTask;
+        
+        // Helpers
+
+        /// <summary>
+        /// Creates a new project asynchronously with the specified project name and returns the created project's details.
+        /// </summary>
+        /// <param name="projectName">The name of the project to be created.</param>
+        /// <returns>A task representing the asynchronous operation. The result contains the details of the created project, or null if deserialization fails.</returns>
+        private async Task<ProjectResponse?> CreateProjectAsync(string projectName)
+        {
+            var payload = new CreateProjectRequest(
+                ProjectName: projectName,
+                Description: "Test project",
+                Visibility: ProjectVisibility.Public
+            );
+
+            var response = await _client.PostAsJsonAsync("/api/v1/projects/create", payload);
+            response.EnsureSuccessStatusCode();
+
+            var created = await response.Content.ReadFromJsonAsync<ProjectResponse>();
+            return created;
+        }
+
+        /// <summary>
+        /// Registers a new user and logs them in, setting the authentication token in the HTTP client header for subsequent requests.
+        /// </summary>
+        /// <exception cref="InvalidOperationException">Thrown when the authentication response does not contain an access token.</exception>
+        /// <returns>A task that represents the asynchronous operation of registering and logging in a user.</returns>
+        private async Task RegisterAndLoginUser()
+        {
+            var email = "[email protected]";
+            var password = "Test1234!";
+            var userName = "testuser";
+
+            var registerPayload = new RegisterRequest(Username:userName, Email: email, Password: password);
+            var registerResponse = await _client.PostAsJsonAsync("/api/v1/auth/register", registerPayload);
+            registerResponse.EnsureSuccessStatusCode();
+
+            var loginPayload = new LoginRequest(Identifier: email, Password: password);
+            var loginResponse = await _client.PostAsJsonAsync("/api/v1/auth/login", loginPayload);
+            
+            loginResponse.EnsureSuccessStatusCode();
+
+            var loginContent = await loginResponse.Content.ReadFromJsonAsync<AuthResponse>();
+
+            if (loginContent?.AccessToken is null)
+            {
+                throw new InvalidOperationException("Auth response did not contain access token");
+            }
+
+            _client.DefaultRequestHeaders.Authorization =
+                new AuthenticationHeaderValue("Bearer", loginContent.AccessToken);
+        }
+        
+        // Tests
+        [Fact]
+        public async Task CreateProject_Should_Create_Project_For_Authenticated_User()
+        {
+            await RegisterAndLoginUser();
+            var projectName = "MyTestProject";
+
+            var created = await CreateProjectAsync(projectName);
+
+            Assert.NotNull(created);
+            Assert.Equal(projectName, created.ProjectName);
+        }
+    }
+}

sparkly-server.test/TestWebAppliactionFactory.cs

@@ -5,46 +5,47 @@
 using Microsoft.Extensions.DependencyInjection;
 using sparkly_server.Infrastructure;
 
-namespace Sparkly.Tests.Infrastructure;
-
-public class TestWebApplicationFactory : WebApplicationFactory<Program>
+namespace sparkly_server.test
 {
-    protected override void ConfigureWebHost(IWebHostBuilder builder)
+    public class TestWebApplicationFactory : WebApplicationFactory<Program>
     {
-        builder.UseEnvironment("Testing");
-        
-        builder.ConfigureAppConfiguration((config) =>
+        protected override void ConfigureWebHost(IWebHostBuilder builder)
         {
-            var settings = new Dictionary<string, string?>
+            builder.UseEnvironment("Testing");
+        
+            builder.ConfigureAppConfiguration((config) =>
             {
-                ["SPARKLY_JWT_KEY"] = "this-is-very-long-test-jwt-key-123456",
-                ["SPARKLY_JWT_ISSUER"] = "sparkly-test-issuer"
-            };
+                var settings = new Dictionary<string, string?>
+                {
+                    ["SPARKLY_JWT_KEY"] = "this-is-very-long-test-jwt-key-123456",
+                    ["SPARKLY_JWT_ISSUER"] = "sparkly-test-issuer"
+                };
 
-            config.AddInMemoryCollection(settings);
-        });
-
-        builder.ConfigureServices(services =>
-        {
-            var descriptor = services.SingleOrDefault(
-                d => d.ServiceType == typeof(DbContextOptions<AppDbContext>));
+                config.AddInMemoryCollection(settings);
+            });
 
-            if (descriptor is not null)
+            builder.ConfigureServices(services =>
             {
-                services.Remove(descriptor);
-            }
+                var descriptor = services.SingleOrDefault(
+                    d => d.ServiceType == typeof(DbContextOptions<AppDbContext>));
 
-            services.AddDbContext<AppDbContext>(options =>
-            {
-                options.UseInMemoryDatabase("sparkly-tests");
-            });
+                if (descriptor is not null)
+                {
+                    services.Remove(descriptor);
+                }
 
-            var sp = services.BuildServiceProvider();
+                services.AddDbContext<AppDbContext>(options =>
+                {
+                    options.UseInMemoryDatabase("sparkly-tests");
+                });
 
-            using var scope = sp.CreateScope();
-            var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
-            db.Database.EnsureDeleted();
-            db.Database.EnsureCreated();
-        });
+                var sp = services.BuildServiceProvider();
+
+                using var scope = sp.CreateScope();
+                var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
+                db.Database.EnsureDeleted();
+                db.Database.EnsureCreated();
+            });
+        }
     }
 }

sparkly-server.test/UserTest.cs

@@ -1,11 +1,10 @@
 using Microsoft.Extensions.DependencyInjection;
 using sparkly_server.DTO.Auth;
 using sparkly_server.Infrastructure;
-using Sparkly.Tests.Infrastructure;
 using System.Text;
 using System.Text.Json;
 
-namespace sparkly_server.Services.Users.test
+namespace sparkly_server.test
 {
     public class UserTest : IClassFixture<TestWebApplicationFactory>, IAsyncLifetime
     {
@@ -29,7 +28,16 @@ public async Task InitializeAsync()
         }
 
         public Task DisposeAsync() => Task.CompletedTask;
-        
+
+        /// <summary>
+        /// Registers a test user in the system by sending a registration request to the API.
+        /// </summary>
+        /// <param name="userName">The username of the user to register.</param>
+        /// <param name="email">The email address of the user to register.</param>
+        /// <param name="password">The password of the user to register.</param>
+        /// <returns>A task that represents the asynchronous operation.</returns>
+
+        // Helper
         private async Task RegisterTestUserAsync(string userName, string email, string password)
         {
             var payload = new RegisterRequest(Username: userName, Email: email, Password: password);
@@ -44,6 +52,7 @@ private async Task RegisterTestUserAsync(string userName, string email, string p
             response.EnsureSuccessStatusCode();
         }
 
+        // Tests
         [Fact]
         public async Task User_CanBeCreated()
         {

src/Domain/Auth/RefreshToken.cs

@@ -27,6 +27,11 @@ public RefreshToken(Guid userId, string token, DateTime expiresAt)
             ExpiresAt = expiresAt;
         }
 
+        /// <summary>
+        /// Revokes the refresh token by marking it as no longer active.
+        /// </summary>
+        /// <param name="ip">The IP address from which the revoke operation is made.</param>
+        /// <param name="replacedByToken">An optional new token that replaces the current token.</param>
         public void Revoke(string? ip = null, string? replacedByToken = null)
         {
             if (RevokedAt is not null)

src/Domain/Projects/Project.cs

@@ -93,7 +93,6 @@ private static string NormalizeSlug(string value)
          public void Rename(string newName)
         {
             SetNameInternal(newName);
-            // Jeśli chcesz, aby slug szedł za nazwą:
             Slug = NormalizeSlug(newName);
             Touch();
         }

src/Services/Auth/AuthService.cs

@@ -20,6 +20,13 @@ public AuthService(IUserService userService,
             _db = db;
         }
 
+        /// <summary>
+        /// Authenticates a user based on the provided credentials and generates an authentication result containing tokens.
+        /// </summary>
+        /// <param name="identifier">The user's identifier, such as username or email address.</param>
+        /// <param name="password">The user's password.</param>
+        /// <param name="ct">A cancellation token to observe while awaiting the task.</param>
+        /// <returns>An AuthResult object containing the access token, refresh token, and their expiry times, or null if authentication fails.</returns>
         public async Task<AuthResult?> LoginAsync(string identifier, string password, CancellationToken ct = default)
         {
             var user = await _userService.ValidateUserAsync(identifier, password, ct);
@@ -51,6 +58,12 @@ public AuthService(IUserService userService,
             );
         }
 
+        /// <summary>
+        /// Refreshes the user's authentication tokens by validating the provided refresh token and generating a new access token.
+        /// </summary>
+        /// <param name="refreshToken">The existing refresh token issued to the user for renewing authentication.</param>
+        /// <param name="ct">A cancellation token to observe while performing the refresh operation.</param>
+        /// <returns>An AuthResult object containing the new access token, the provided refresh token, and their respective expiry times. Returns null if the refresh token is invalid or inactive.</returns>
         public async Task<AuthResult> RefreshAsync(string refreshToken, CancellationToken ct = default)
         {
             if (string.IsNullOrWhiteSpace(refreshToken))
@@ -81,6 +94,12 @@ public async Task<AuthResult> RefreshAsync(string refreshToken, CancellationToke
             );
         }
 
+        /// <summary>
+        /// Revokes a refresh token to log the user out by marking the token as revoked in the database.
+        /// </summary>
+        /// <param name="refreshToken">The token to be revoked, which identifies the user session.</param>
+        /// <param name="ct">A cancellation token to observe while awaiting the task.</param>
+        /// <returns>A Task representing the asynchronous operation.</returns>
         public async Task LogoutAsync(string refreshToken, CancellationToken ct = default)
         {
             if (string.IsNullOrWhiteSpace(refreshToken))

src/Services/Auth/JwtProvider.cs

@@ -20,6 +20,11 @@ public JwtProvider(IConfiguration config)
             _audience = config["SPARKLY_JWT_AUDIENCE"] ?? "sparkly-api";
         }
 
+        /// <summary>
+        /// Generates a JWT access token for the given user.
+        /// </summary>
+        /// <param name="user">The user for whom the access token is being generated. The user object should contain details like Id, Email, UserName, and Role.</param>
+        /// <returns>A string representing the generated JWT access token.</returns>
         public string GenerateAccessToken(User user)
         {
             var claims = new List<Claim>
@@ -46,6 +51,10 @@ public string GenerateAccessToken(User user)
             return new JwtSecurityTokenHandler().WriteToken(token);
         }
 
+        /// <summary>
+        /// Generates a secure refresh token to be used for renewing access tokens.
+        /// </summary>
+        /// <returns>A string representing the generated refresh token.</returns>
         public string GenerateRefreshToken()
         {
             // na razie prosty generator; później można dodać zapisywanie do bazy