From 8e09ab34b54718af7753ba7d7e4e370ab14efa1a Mon Sep 17 00:00:00 2001
From: Syndamia <kamen.d.mladenov@protonmail.com>
Date: Thu, 4 Feb 2021 15:31:49 +0200
Subject: Added some XML documentation to Service layer (where really needed)

---
 src/DevHive.Services/Services/UserService.cs | 32 ++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

(limited to 'src/DevHive.Services/Services/UserService.cs')

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);
-- 
cgit v1.2.3