Added some XML documentation to Service layer (where really needed)

4 files changed, 73 insertions, 1 deletions

diff --git a/src/DevHive.Services/Services/CommentService.cs b/src/DevHive.Services/Services/CommentService.cs
index e0eb88a..1ea775c 100644
--- a/src/DevHive.Services/Services/CommentService.cs
+++ b/src/DevHive.Services/Services/CommentService.cs
@@ -103,6 +103,9 @@ namespace DevHive.Services.Services
 		#endregion
 
 		#region Validations
+		/// <summary>
+        /// Checks whether the user Id in the token and the given user Id match
+        /// </summary>
 		public async Task<bool> ValidateJwtForCreating(Guid userId, string rawTokenData)
 		{
 			User user = await this.GetUserForValidation(rawTokenData);
@@ -110,6 +113,11 @@ namespace DevHive.Services.Services
 			return user.Id == userId;
 		}
 
+		/// <summary>
+        /// Checks whether the comment, gotten with the commentId,
+		/// is made by the user in the token
+		/// or if the user in the token is an admin
+        /// </summary>
 		public async Task<bool> ValidateJwtForComment(Guid commentId, string rawTokenData)
 		{
 			Comment comment = await this._commentRepository.GetByIdAsync(commentId) ??
@@ -126,6 +134,9 @@ namespace DevHive.Services.Services
 				return false;
 		}
 
+		/// <summary>
+        /// Returns the user, via their Id in the token
+        /// </summary>
 		private async Task<User> GetUserForValidation(string rawTokenData)
 		{
 			JwtSecurityToken jwt = new JwtSecurityTokenHandler().ReadJwtToken(rawTokenData.Remove(0, 7));
@@ -139,7 +150,9 @@ namespace DevHive.Services.Services
 			return user;
 		}
 
-
+		/// <summary>
+        /// Returns all values from a given claim type
+        /// </summary>
 		private List<string> GetClaimTypeValues(string type, IEnumerable<Claim> claims)
 		{
 			List<string> toReturn = new();
diff --git a/src/DevHive.Services/Services/FeedService.cs b/src/DevHive.Services/Services/FeedService.cs
index b9d1922..671df60 100644
--- a/src/DevHive.Services/Services/FeedService.cs
+++ b/src/DevHive.Services/Services/FeedService.cs
@@ -24,6 +24,10 @@ namespace DevHive.Services.Services
 			this._mapper = mapper;
 		}
 
+		/// <summary>
+		/// This method is used in the feed page.
+		/// See the FeedRepository "GetFriendsPosts" menthod for more information on how it works.
+        /// </summary>
 		public async Task<ReadPageServiceModel> GetPage(GetPageServiceModel model)
 		{
 			User user = null;
@@ -53,6 +57,10 @@ namespace DevHive.Services.Services
 			return readPageServiceModel;
 		}
 
+		/// <summary>
+		/// This method is used in the profile pages.
+		/// See the FeedRepository "GetUsersPosts" menthod for more information on how it works.
+        /// </summary>
 		public async Task<ReadPageServiceModel> GetUserPage(GetPageServiceModel model)
 		{
 			User user = null;
diff --git a/src/DevHive.Services/Services/PostService.cs b/src/DevHive.Services/Services/PostService.cs
index 6dbb272..16d6611 100644
--- a/src/DevHive.Services/Services/PostService.cs
+++ b/src/DevHive.Services/Services/PostService.cs
@@ -138,6 +138,9 @@ namespace DevHive.Services.Services
 		#endregion
 
 		#region Validations
+		/// <summary>
+        /// Checks whether the user Id in the token and the given user Id match
+        /// </summary>
 		public async Task<bool> ValidateJwtForCreating(Guid userId, string rawTokenData)
 		{
 			User user = await this.GetUserForValidation(rawTokenData);
@@ -145,6 +148,11 @@ namespace DevHive.Services.Services
 			return user.Id == userId;
 		}
 
+		/// <summary>
+        /// Checks whether the post, gotten with the postId,
+		/// is made by the user in the token
+		/// or if the user in the token is an admin
+        /// </summary>
 		public async Task<bool> ValidateJwtForPost(Guid postId, string rawTokenData)
 		{
 			Post post = await this._postRepository.GetByIdAsync(postId) ??
@@ -161,6 +169,11 @@ namespace DevHive.Services.Services
 				return false;
 		}
 
+		/// <summary>
+        /// Checks whether the comment, gotten with the commentId,
+		/// is made by the user in the token
+		/// or if the user in the token is an admin
+        /// </summary>
 		public async Task<bool> ValidateJwtForComment(Guid commentId, string rawTokenData)
 		{
 			Comment comment = await this._commentRepository.GetByIdAsync(commentId) ??
@@ -177,6 +190,9 @@ namespace DevHive.Services.Services
 				return false;
 		}
 
+		/// <summary>
+        /// Returns the user, via their Id in the token
+        /// </summary>
 		private async Task<User> GetUserForValidation(string rawTokenData)
 		{
 			JwtSecurityToken jwt = new JwtSecurityTokenHandler().ReadJwtToken(rawTokenData.Remove(0, 7));
@@ -190,6 +206,9 @@ namespace DevHive.Services.Services
 			return user;
 		}
 
+		/// <summary>
+        /// Returns all values from a given claim type
+        /// </summary>
 		private List<string> GetClaimTypeValues(string type, IEnumerable<Claim> claims)
 		{
 			List<string> toReturn = new();
diff --git a/src/DevHive.Services/Services/UserService.cs b/src/DevHive.Services/Services/UserService.cs
index ae1760f..3feca9f 100644
--- a/src/DevHive.Services/Services/UserService.cs
+++ b/src/DevHive.Services/Services/UserService.cs
@@ -47,6 +47,10 @@ namespace DevHive.Services.Services
 		}
 
 		#region Authentication
+		/// <summary>
+        /// Adds a new user to the database with the values from the given model.
+		/// Returns a JSON Web Token (that can be used for authorization)
+        /// </summary>
 		public async Task<TokenModel> LoginUser(LoginServiceModel loginModel)
 		{
 			if (!await this._userRepository.DoesUsernameExistAsync(loginModel.UserName))
@@ -60,6 +64,9 @@ namespace DevHive.Services.Services
 			return new TokenModel(WriteJWTSecurityToken(user.Id, user.UserName, user.Roles));
 		}
 
+		/// <summary>
+        /// Returns a new JSON Web Token (that can be used for authorization) for the given user
+        /// </summary>
 		public async Task<TokenModel> RegisterUser(RegisterServiceModel registerModel)
 		{
 			if (await this._userRepository.DoesUsernameExistAsync(registerModel.UserName))
@@ -125,6 +132,9 @@ namespace DevHive.Services.Services
 			return this._userMapper.Map<UserServiceModel>(newUser);
 		}
 
+		/// <summary>
+        /// Uploads the given picture and assigns it's link to the user in the database
+        /// </summary>
 		public async Task<ProfilePictureServiceModel> UpdateProfilePicture(UpdateProfilePictureServiceModel updateProfilePictureServiceModel)
 		{
 			User user = await this._userRepository.GetByIdAsync(updateProfilePictureServiceModel.UserId);
@@ -162,6 +172,11 @@ namespace DevHive.Services.Services
 		#endregion
 
 		#region Validations
+		/// <summary>
+        /// Checks whether the given user, gotten by the "id" property,
+		/// is the same user as the one in the token (uness the user in the token has the admin role)
+		/// and the roles in the token are the same as those in the user, gotten by the id in the token
+        /// </summary>
 		public async Task<bool> ValidJWT(Guid id, string rawTokenData)
 		{
 			// There is authorization name in the beginning, i.e. "Bearer eyJh..."
@@ -197,6 +212,9 @@ namespace DevHive.Services.Services
 			return true;
 		}
 
+		/// <summary>
+        /// Returns all values from a given claim type
+        /// </summary>
 		private List<string> GetClaimTypeValues(string type, IEnumerable<Claim> claims)
 		{
 			List<string> toReturn = new();
@@ -208,6 +226,11 @@ namespace DevHive.Services.Services
 			return toReturn;
 		}
 
+		/// <summary>
+        /// Checks whether the user in the model exists
+		/// and whether the username in the model is already taken.
+		/// If the check fails (is false), it throws an exception, otherwise nothing happens
+        /// </summary>
 		private async Task ValidateUserOnUpdate(UpdateUserServiceModel updateUserServiceModel)
 		{
 			if (!await this._userRepository.DoesUserExistAsync(updateUserServiceModel.Id))
@@ -218,6 +241,10 @@ namespace DevHive.Services.Services
 				throw new ArgumentException("Username already exists!");
 		}
 
+		/// <summary>
+        /// Return a new JSON Web Token, containing the user id, username and roles.
+		/// Tokens have an expiration time of 7 days.
+        /// </summary>
 		private string WriteJWTSecurityToken(Guid userId, string username, HashSet<Role> roles)
 		{
 			byte[] signingKey = Encoding.ASCII.GetBytes(_jwtOptions.Secret);
@@ -274,6 +301,11 @@ namespace DevHive.Services.Services
 			return new TokenModel(WriteJWTSecurityToken(newUser.Id, newUser.UserName, newUser.Roles));
 		}
 
+		/// <summary>
+        /// Returns the user with the Id in the model, adding to him the roles, languages and technologies, specified by the parameter model.
+		/// This practically maps HashSet<UpdateRoleServiceModel> to HashSet<Role> (and the equvalent HashSets for Languages and Technologies)
+		/// and assigns the latter to the returned user.
+        /// </summary>
 		private async Task<User> PopulateModel(UpdateUserServiceModel updateUserServiceModel)
 		{
 			User user = this._userMapper.Map<User>(updateUserServiceModel);