From bce0ca9d74a0c2b15febfe08eea651b5bf8025a8 Mon Sep 17 00:00:00 2001
From: Philip Molares <philip.molares@udo.edu>
Date: Fri, 5 Mar 2021 00:26:57 +0100
Subject: [PATCH] UsersService: Add JSDoc to all methods

Signed-off-by: Philip Molares <philip.molares@udo.edu>
---
 src/users/users.service.ts | 35 +++++++++++++++++++++++++++++++++--
 1 file changed, 33 insertions(+), 2 deletions(-)

diff --git a/src/users/users.service.ts b/src/users/users.service.ts
index 7714d0dd5..1ec9de04c 100644
--- a/src/users/users.service.ts
+++ b/src/users/users.service.ts
@@ -7,7 +7,7 @@
 import { Injectable } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
 import { Repository } from 'typeorm';
-import { NotInDBError } from '../errors/errors';
+import { AlreadyInDBError, NotInDBError } from '../errors/errors';
 import { ConsoleLoggerService } from '../logger/console-logger.service';
 import { UserInfoDto } from './user-info.dto';
 import { User } from './user.entity';
@@ -21,11 +21,25 @@ export class UsersService {
     this.logger.setContext(UsersService.name);
   }
 
-  createUser(userName: string, displayName: string): Promise<User> {
+  /**
+   * @async
+   * Create a new user with a given userName and displayName
+   * @param userName - the userName the new user shall have
+   * @param displayName - the display the new user shall have
+   * @return {User} the user
+   * @throws {AlreadyInDBError} the userName is already taken.
+   */
+  async createUser(userName: string, displayName: string): Promise<User> {
     const user = User.create(userName, displayName);
     return this.userRepository.save(user);
   }
 
+  /**
+   * @async
+   * Delete the user with the specified userName
+   * @param userName - the username of the user to be delete
+   * @throws {NotInDBError} the userName has no user associated with it.
+   */
   async deleteUser(userName: string): Promise<void> {
     // TODO: Handle owned notes and edits
     const user = await this.userRepository.findOne({
@@ -34,6 +48,13 @@ export class UsersService {
     await this.userRepository.delete(user);
   }
 
+  /**
+   * @async
+   * Get the user specified by the username
+   * @param {string} userName the username by which the user is specified
+   * @param {boolean} [withTokens=false] if the returned user object should contain authTokens
+   * @return {User} the specified user
+   */
   async getUserByUsername(userName: string, withTokens = false): Promise<User> {
     const user = await this.userRepository.findOne({
       where: { userName: userName },
@@ -45,6 +66,11 @@ export class UsersService {
     return user;
   }
 
+  /**
+   * Extract the photoUrl of the user or in case no photo url is present generate a deterministic user photo
+   * @param {User} user - the specified User
+   * @return the url of the photo
+   */
   getPhotoUrl(user: User): string {
     if (user.photo) {
       return user.photo;
@@ -54,6 +80,11 @@ export class UsersService {
     }
   }
 
+  /**
+   * Build UserInfoDto from a user.
+   * @param {User=} user - the user to use
+   * @return {(UserInfoDto|null)} the built UserInfoDto
+   */
   toUserDto(user: User | null | undefined): UserInfoDto | null {
     if (!user) {
       this.logger.warn(`Recieved ${String(user)} argument!`, 'toUserDto');