Add docs in user and tasks

Author: felipeoriani

src/core/domain/task.ts

@@ -25,6 +25,10 @@ export type TaskUpdateStatusCommand = {
   status: TaskStatus
 }
 
+/**
+ * The `TaskRepository` is an abstraction that represents a storage of tasks.
+ * Its implementation is part of the infrastructure layer.
+ */
 export interface TaskRepository {
   get(id: string): Promise<Task | null>
   getAll(userId?: string): Promise<Task[]>
@@ -34,13 +38,60 @@ export interface TaskRepository {
   delete(id: string): Promise<boolean>
 }
 
+/**
+ * The `TaskUseCases` is a service that is responsable to manage all the `Task` entities on the platform.
+ * Each Task has a owner defined by the `userId` property which limits the access to all the users.
+ * A Task can be handled only by the user owner or a super user.
+ */
 export interface TaskUseCases {
+  /**
+   * Get a Task by a given id based on the current user permissions.
+   * @param id Task id.
+   * @returns Existing task or an error when it does not exists or user is not authorized.
+   */
   getTask(id: string): Promise<Task>
+
+  /**
+   * Get a list of all tasks based on the current user.
+   * @returns Async result containing a list of tasks allowed by the current user.
+   */
   getAllTasks(): Promise<Task[]>
+
+  /**
+   * Get a collection of tasks based on the status.
+   * @param status Status of the Tasks defined by `TaskStatus` enum.
+   * @returns Async result containing a collection of tasks.
+   */
   getTasksByStatus(status: TaskStatus): Promise<Task[]>
+
+  /**
+   * Add a new tasks for the current user.
+   * @param command Valida command representing a Task.
+   * @returns Async result containing a new Task.
+   */
   addNewTask(command: TaskCommand): Promise<Task>
+
+  /**
+   * Update an existing Task by a given id based on the current user permissions.
+   * @param id Id of the task to be updated.
+   * @param command Valid command representing a Task.
+   * @returns Async result containing the updated Task. This operation can also throw an error based on the current user permissions.
+   */
   updateExistingTask(id: string, command: TaskCommand): Promise<Task>
+
+  /**
+   * Update the status of a task. Useful when a user just want to move the Task to a different state. Only owners and admin can change it.
+   * @param id Id of the task.
+   * @param status New state of the task.
+   * @returns Async result containing the updated task. This operation can also throw an error depending on the user permissions.
+   */
   updateStatus(id: string, status: TaskStatus): Promise<Task>
+
+  /**
+   * Delete an existing Task by the id.
+   * @param id Task Id.
+   * @returns Async result containing if the delete operation succeed. This operation can also throw an error depending on the user permissions.
+   */
   deleteTask(id: string): Promise<boolean>
 }
 

src/core/domain/user.ts

@@ -31,9 +31,24 @@ export type UserSession = {
   ipAddress?: string
 }
 
+/**
+ * The `UserUseCases` represents the user-cases for `User` entity.
+ * It holds all the operations around the users including the get user details and part of the authentication process.
+ */
 export interface UserUseCases {
-  authenticateUser(input: AuthenticateUserInput): Promise<User>
+  /**
+   * Get a User by a given id.
+   * @param id User id.
+   * @returns Async result containing a User instance. This operation can also throw an error when the user does not exists.
+   */
   getUserById(id: string): Promise<User | null>
+
+  /**
+   * Validate a user input model for authentication process.
+   * @param input User authentication model.
+   * @returns Async result containing the user when the operation succeed. This operation can also throw an error when the user does not exists or the credentials does not matches.
+   */
+  authenticateUser(input: AuthenticateUserInput): Promise<User>
 }
 
 export interface CurrentUser {

src/core/use-cases/task-use-cases.ts

@@ -5,10 +5,10 @@ import { CurrentUser } from '../domain/user.js'
 import { TaskPrismaRepository } from '../infrastructure/task-repository.js'
 
 /**
- * The `TaskService` is a service that is responsable to manage all the `Task` entities on the platform.
+ * The `TaskService` is a service that implements the `TaskUseCases` which is responsable to manage all the `Task` entities on the platform.
  * This service depends on an abstract `repository` and a user `session` representation.
  * Each Task has a owner defined by the `userId` property which limits the access to all the users.
- * A Task can be handled only by the user owner or admin user.
+ * A Task can be handled only by the user owner or a super user.
  */
 export class TaskService implements TaskUseCases {
   /**