From a98f15d10337fa8829231a336b52b56621a81e85 Mon Sep 17 00:00:00 2001
From: maxime <maximebatista18@gmail.com>
Date: Sun, 17 Mar 2024 10:55:07 +0100
Subject: [PATCH] add documentation on services

---
 Services/ITacticService.cs | 96 ++++++++++++++++++++++++++++++++------
 Services/ITeamService.cs   | 60 +++++++++++++++++++-----
 Services/UserService.cs    | 38 +++++++++++++--
 3 files changed, 165 insertions(+), 29 deletions(-)

diff --git a/Services/ITacticService.cs b/Services/ITacticService.cs
index 98d68e7..9f443ac 100644
--- a/Services/ITacticService.cs
+++ b/Services/ITacticService.cs
@@ -2,25 +2,95 @@ using Model;
 
 namespace Services;
 
+/// <summary>
+/// Represents a service interface for managing tactics.
+/// </summary>
 public interface ITacticService
 {
+    /// <summary>
+    /// Retrieves a list of tactics owned by the specified user.
+    /// </summary>
+    /// <param name="userId">The ID of the user.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains a list of tactics.</returns>
+    Task<IEnumerable<Tactic>> ListTacticsOf(int userId);
 
-    public Task<IEnumerable<Tactic>> ListTacticsOf(int userId);
-    
-    public Task<bool> HasAnyRights(int userId, int tacticId);
+    /// <summary>
+    /// Checks if the user has any rights to access the specified tactic.
+    /// </summary>
+    /// <param name="userId">The ID of the user.</param>
+    /// <param name="tacticId">The ID of the tactic.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains a boolean indicating whether the user has rights.</returns>
+    Task<bool> HasAnyRights(int userId, int tacticId);
 
+    /// <summary>
+    /// Adds a new tactic for the specified user.
+    /// </summary>
+    /// <param name="userId">The ID of the user.</param>
+    /// <param name="name">The name of the tactic.</param>
+    /// <param name="courtType">The type of court.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the ID of the newly added tactic.</returns>
+    Task<int> AddTactic(int userId, string name, CourtType courtType);
 
-    public Task<int> AddTactic(int userId, string name, CourtType courtType);
+    /// <summary>
+    /// Updates the name of the specified tactic.
+    /// </summary>
+    /// <param name="tacticId">The ID of the tactic.</param>
+    /// <param name="name">The new name of the tactic.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains a boolean indicating whether the update was successful.</returns>
+    Task<bool> UpdateName(int tacticId, string name);
 
-    public Task<bool> UpdateName(int tacticId, string name);
-    public Task<bool> SetTacticStepContent(int tacticId, int stepId, string json);
-    public Task<string?> GetTacticStepContent(int tacticId, int stepId);
+    /// <summary>
+    /// Sets the content of a tactic step.
+    /// </summary>
+    /// <param name="tacticId">The ID of the tactic.</param>
+    /// <param name="stepId">The ID of the step.</param>
+    /// <param name="json">The JSON content to set.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains a boolean indicating whether the operation was successful.</returns>
+    Task<bool> SetTacticStepContent(int tacticId, int stepId, string json);
 
-    public Task<Tactic?> GetTactic(int tacticId);
+    /// <summary>
+    /// Retrieves the content of a tactic step.
+    /// </summary>
+    /// <param name="tacticId">The ID of the tactic.</param>
+    /// <param name="stepId">The ID of the step.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the JSON content of the step.</returns>
+    Task<string?> GetTacticStepContent(int tacticId, int stepId);
 
-    public Task<TacticStep> GetRootStep(int tacticId);
-    
-    public Task<IEnumerable<Tactic>> ListUserTactics(int userId);
-    public Task<int?> AddTacticStep(int tacticId, int parentStepId, string initialJson);
-    public Task<bool> RemoveTacticStep(int tacticId, int stepId);
+    /// <summary>
+    /// Retrieves the root step of the specified tactic.
+    /// </summary>
+    /// <param name="tacticId">The ID of the tactic.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the root step of the tactic.</returns>
+    Task<TacticStep> GetRootStep(int tacticId);
+
+    /// <summary>
+    /// Retrieves the tactic with the specified ID.
+    /// </summary>
+    /// <param name="tacticId">The ID of the tactic.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the tactic.</returns>
+    Task<Tactic?> GetTactic(int tacticId);
+
+    /// <summary>
+    /// Retrieves a list of tactics owned by the specified user.
+    /// </summary>
+    /// <param name="userId">The ID of the user.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains a list of tactics.</returns>
+    Task<IEnumerable<Tactic>> ListUserTactics(int userId);
+
+    /// <summary>
+    /// Adds a new step to the specified tactic.
+    /// </summary>
+    /// <param name="tacticId">The ID of the tactic.</param>
+    /// <param name="parentStepId">The ID of the parent step.</param>
+    /// <param name="initialJson">The initial JSON content of the step.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the ID of the newly added step.</returns>
+    Task<int?> AddTacticStep(int tacticId, int parentStepId, string initialJson);
+
+    /// <summary>
+    /// Removes the specified step from the tactic, along with its child steps if any.
+    /// </summary>
+    /// <param name="tacticId">The ID of the tactic.</param>
+    /// <param name="stepId">The ID of the step to remove.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains a boolean indicating whether the removal was successful.</returns>
+    Task<bool> RemoveTacticStep(int tacticId, int stepId);
 }
\ No newline at end of file
diff --git a/Services/ITeamService.cs b/Services/ITeamService.cs
index 1853f76..d806fb6 100644
--- a/Services/ITeamService.cs
+++ b/Services/ITeamService.cs
@@ -2,26 +2,61 @@ using Model;
 
 namespace Services;
 
+/// <summary>
+/// Represents a service for managing teams.
+/// </summary>
 public interface ITeamService
 {
-    public Task<IEnumerable<Team>> ListTeamsOf(int userId);
+    /// <summary>
+    /// Lists all teams associated with the specified <paramref name="userId"/>.
+    /// </summary>
+    Task<IEnumerable<Team>> ListTeamsOf(int userId);
 
+    /// <summary>
+    /// Lists a range of teams.
+    /// </summary>
+    Task<IEnumerable<Team>> ListTeams(int start, int count);
 
-    public Task<IEnumerable<Team>> ListTeams(int start, int count);
-    public Task<int> CountTotalTeams();
+    /// <summary>
+    /// Retrieves the total count of teams.
+    /// </summary>
+    Task<int> CountTotalTeams();
 
-    public Task<Team> AddTeam(string name, string picture, string firstColor, string secondColor);
-    public Task RemoveTeams(params int[] teams);
+    /// <summary>
+    /// Adds a new team.
+    /// </summary>
+    Task<Team> AddTeam(string name, string picture, string firstColor, string secondColor);
 
-    public Task<IEnumerable<Member>> GetMembersOf(int teamId);
+    /// <summary>
+    /// Removes one or more teams.
+    /// </summary>
+    Task RemoveTeams(params int[] teams);
 
-    public Task<Member?> AddMember(int teamId, int userId, MemberRole role);
-    
-    public Task<bool> UpdateMember(Member member);
+    /// <summary>
+    /// Updates an existing team.
+    /// </summary>
+    Task<bool> UpdateTeam(Team team);
 
-    public Task<bool> RemoveMember(int teamId, int userId);
+    /// <summary>
+    /// Retrieves the members of the specified team.
+    /// </summary>
+    Task<IEnumerable<Member>> GetMembersOf(int teamId);
+
+    /// <summary>
+    /// Adds a new member to the team.
+    /// </summary>
+    Task<Member?> AddMember(int teamId, int userId, MemberRole role);
+
+    /// <summary>
+    /// Updates the role of a member within the team.
+    /// </summary>
+    Task<bool> UpdateMember(Member member);
+
+    /// <summary>
+    /// Removes a member from the team.
+    /// </summary>
+    Task<bool> RemoveMember(int teamId, int userId);
 
-    public Task<bool> UpdateTeam(Team team);
 
     enum TeamAccessibility
     {
@@ -29,10 +64,12 @@ public interface ITeamService
          * The Team or the user is not found
          */
         NotFound,
+
         /**
          * Accessibility not granted
          */
         Unauthorized,
+
         /**
          * Accessibility granted
          */
@@ -45,5 +82,4 @@ public interface ITeamService
      * given team.
      */
     public Task<TeamAccessibility> EnsureAccessibility(int userId, int teamId, MemberRole role);
-
 }
\ No newline at end of file
diff --git a/Services/UserService.cs b/Services/UserService.cs
index 3639347..ca3de87 100644
--- a/Services/UserService.cs
+++ b/Services/UserService.cs
@@ -2,23 +2,53 @@
 
 namespace Services;
 
+/// <summary>
+/// Represents a service for managing users.
+/// </summary>
 public interface IUserService
 {
-
+    /// <summary>
+    /// Retrieves the count of users whose names contain the specified needle.
+    /// </summary>
     Task<int> UsersCount(string nameNeedle);
+
+    /// <summary>
+    /// Retrieves the total count of users.
+    /// </summary>
     Task<int> UsersCount();
-    
+
+    /// <summary>
+    /// Lists a range of users, optionally filtering by name.
+    /// </summary>
     Task<IEnumerable<User>> ListUsers(int start, int count, string? nameNeedle = null);
 
+    /// <summary>
+    /// Retrieves the user with the specified ID.
+    /// </summary>
     Task<User?> GetUser(int id);
+
+    /// <summary>
+    /// Retrieves the user with the specified email.
+    /// </summary>
     Task<User?> GetUser(string email);
 
+    /// <summary>
+    /// Creates a new user.
+    /// </summary>
     Task<User> CreateUser(string username, string email, string password, string profilePicture, bool isAdmin);
 
+    /// <summary>
+    /// Removes one or more users.
+    /// </summary>
     Task<bool> RemoveUsers(params int[] identifiers);
 
+    /// <summary>
+    /// Updates an existing user.
+    /// </summary>
     Task UpdateUser(User user);
-    
-    public Task<User?> Authorize(string email, string password);
 
+    /// <summary>
+    /// Authorizes a user with the specified email and password.
+    /// </summary>
+    Task<User?> Authorize(string email, string password);
 }
\ No newline at end of file