feat: format the inline documentation (#9)

Author: JosemaPereira

.eslintrc.json

@@ -7,7 +7,8 @@
   "extends": [
     "airbnb-base",
     "prettier",
-    "plugin:prettier/recommended"
+    "plugin:prettier/recommended",
+    "plugin:jsdoc/recommended"
   ],
   "ignorePatterns": [
     "/dist"
@@ -18,9 +19,11 @@
   },
   "plugins": [
     "prettier",
-    "jest"
+    "jest",
+    "jsdoc"
   ],
   "rules": {
+    "valid-jsdoc": "off",
     "prettier/prettier": "error",
     "no-console": "warn",
     "arrow-body-style": [
@@ -66,5 +69,10 @@
         "devDependencies": true
       }
     ]
+  },
+  "settings": {
+    "jsdoc": {
+      "mode": "typescript"
+    }
   }
 }

.gitignore

@@ -2,4 +2,6 @@ node_modules/
 coverage/
 dist/
 .vscode/
-.env
+.env
+out/
+docs/

app/index.js

@@ -1,6 +1,19 @@
 import App from './server';
 
-const PORT = 3001;
+/**
+ * The port on which the server will listen.
+ * @type {number}
+ */
+const { PORT } = process.env;
+
+/**
+ * Start the server and listen on the specified port.
+ * @function
+ * @name startServer
+ * @param {number} port - The port number on which the server will listen.
+ * @param {Function} callback - A callback function to be executed once the server is listening.
+ * @returns {void}
+ */
 App.listen(PORT, () => {
-  console.log(`App listen at http://localhost:${PORT}`);
+  console.log(`App listen at http://localhost:${process.env.PORT}`);
 });

app/internal/adapters/auth/jwt.js

@@ -1,41 +1,32 @@
+/**
+ * @module Auth/JWT
+ */
+
 import jsonwebtoken from 'jsonwebtoken';
 
 /**
  * Generates a JSON Web Token (JWT) for the specified admin ID and expiration time.
- *
  * @function
- * @memberof JWT
- * @param {string} adminID - The ID of the admin for whom the token is generated.
+ * @param {string} adminID - The ID for whom the token is generated.
  * @param {string | number} expiresIn - The expiration time for the token (e.g., '2h', '7d', or a timestamp).
- * @param {string} secretKey - Security secretKey.
- * @returns {string} The generated JWT.
+ * @param {string} secretKey - The secret key used to sign the JWT token.
+ * @returns {string} The generated JWT token.
  */
 const generateToken = (adminID, expiresIn, secretKey) =>
   jsonwebtoken.sign({ id: adminID }, secretKey, {
     expiresIn,
   });
 
 /**
- * Verifies the authenticity of a JSON Web Token (JWT).
- *
+ * Verifies the authenticity of a JWT token.
  * @function
- * @memberof JWT
- * @param {string} token - The JWT to be verified.
- * @param {string} secretKey - The JWT secretKey used to be verify.
- * @returns {object} The decoded payload of the verified JWT.
- * @throws {Error} If the token verification fails.
+ * @param {string} token - The JWT token to be verified.
+ * @param {string} secretKey - The secret key used to verify the JWT token.
+ * @returns {string} The decoded payload of the verified JWT.
+ * @throws {Error} If the token is invalid or has expired.
  */
 const verifyToken = (token, secretKey) => jsonwebtoken.verify(token, secretKey);
 
-/**
- * JSON Web Token (JWT) utility functions for token generation and verification.
- *
- * @namespace
- * @typedef {Object} JWT
- * @property {function} generateToken - Function to generate a JWT.
- * @property {function} verifyToken - Function to verify the authenticity of a JWT.
- */
-
 export const JWT = {
   generateToken,
   verifyToken,

app/internal/adapters/index.js

@@ -1,5 +1,12 @@
-import { MainRoute, UsersRoute, AuthRoute } from './routes';
+import { JWT } from './auth';
+import { AuthRoute, MainRoute, UsersRoute } from './routes';
 
+/**
+ * Adapters module containing various adapters.
+ * @property {object} Auth - Authentication adapter.
+ * @property {object} Routes - Routes adapter.
+ */
 export const Adapters = {
-  Routes: { MainRoute, UsersRoute, AuthRoute },
+  Auth: { JWT },
+  Routes: { MainRoute, AuthRoute, UsersRoute },
 };

app/internal/adapters/routes/auth.routes.js

@@ -1,14 +1,17 @@
+/**
+ * @module Routes/Auth
+ */
+
 import express from 'express';
 import { AuthController } from '../../core/controllers';
 
 /**
- * Create a new instance of UserRoutes.
- * @param {express.Application} app - The Express application instance.
+ * Set up routes related to authentication.
+ * @function AuthRoute
+ * @param {express.Application} app - The Express application.
  */
 export const AuthRoute = (app) => {
   const router = express.Router();
   app.use('/auth', router);
-
-  // Get Token
   router.get('/token', AuthController.getToken);
 };

app/internal/adapters/routes/main.routes.js

@@ -1,9 +1,14 @@
+/**
+ * @module Routes/Main
+ */
+
 import express from 'express';
 import { MainController } from '../../core/controllers';
 
 /**
- * Create a new instance of MainRoutes.
- * @param {express.Application} app - The Express application instance.
+ * Set up main routes.
+ * @function MainRoute
+ * @param {express.Application} app - The Express application.
  */
 export const MainRoute = (app) => {
   const router = express.Router();

app/internal/adapters/routes/users.routes.js

@@ -1,9 +1,14 @@
+/**
+ * @module Routes/Users
+ */
+
 import express from 'express';
 import { UsersController } from '../../core/controllers';
 
 /**
- * Create a new instance of UserRoutes.
- * @param {express.Application} app - The Express application instance.
+ * Set up routes related to Users CRUD operations
+ * @function UsersRoute
+ * @param {express.Application} app - The Express application.
  */
 export const UsersRoute = (app) => {
   const router = express.Router();

app/internal/core/controllers/auth.controller.js

@@ -1,24 +1,30 @@
+/**
+ * @module Controllers/Auth
+ */
+
 import { constants } from 'http2';
 import { AuthServices } from '../services';
 
 /**
- * Callback function for performing a CRUD.
+ * Callback function getting a token.
+ * @function
  * @param {import('express').Request} req - Express request object.
  * @param {import('express').Response} res - Express response object.
  * @param {import('express').NextFunction} next - Express next middleware function.
- * @function getToken - Obtain the JWT token.
  */
+const getToken = (req, res, next) => {
+  try {
+    const token = AuthServices.getToken(
+      req.body.adminId,
+      req.config.auth.expiresIn,
+      req.config.auth.securityKey,
+    );
+    res.status(constants.HTTP_STATUS_OK).json(token);
+  } catch (err) {
+    next(err);
+  }
+};
+
 export const AuthController = {
-  getToken: (req, res, next) => {
-    try {
-      const token = AuthServices.getToken(
-        req.body.adminId,
-        req.config.auth.expiresIn,
-        req.config.auth.securityKey,
-      );
-      res.status(constants.HTTP_STATUS_OK).json(token);
-    } catch (err) {
-      next(err);
-    }
-  },
+  getToken,
 };

app/internal/core/controllers/main.controller.js

@@ -1,8 +1,13 @@
+/**
+ * @module Controllers/Main
+ */
+
 import { constants } from 'http2';
 import { MainServices } from '../services';
 
 /**
- * Callback function for performing a health check.
+ * Callback function the health check.
+ * @function
  * @param {import('express').Request} req - Express request object.
  * @param {import('express').Response} res - Express response object.
  * @param {import('express').NextFunction} next - Express next middleware function.

app/internal/core/controllers/users.controller.js

@@ -1,47 +1,76 @@
+/**
+ * @module Controllers/Users
+ */
 import { constants } from 'http2';
 import { UserServices } from '../services';
 
 /**
- * Callback function for performing a CRUD.
+ * Callback function for getting a user by id.
+ * @function
  * @param {import('express').Request} req - Express request object.
  * @param {import('express').Response} res - Express response object.
  * @param {import('express').NextFunction} next - Express next middleware function.
- * @function getByID - Obtain the information of a user using an ID.
- * @function create - Create a new user.
- * @function update - RRefresh the information of  a user using  his ID.
- * @function delete - Delete the information of a user using his ID.
  */
+const getById = (req, res, next) => {
+  try {
+    const message = UserServices.getById();
+    res.status(constants.HTTP_STATUS_OK).json(message);
+  } catch (err) {
+    next(err);
+  }
+};
+
+/**
+ * Callback function for create a user.
+ * @function
+ * @param {import('express').Request} req - Express request object.
+ * @param {import('express').Response} res - Express response object.
+ * @param {import('express').NextFunction} next - Express next middleware function.
+ */
+const create = async (req, res, next) => {
+  try {
+    const message = UserServices.create();
+    res.status(constants.HTTP_STATUS_OK).json(message);
+  } catch (err) {
+    next(err);
+  }
+};
+
+/**
+ * Callback function for update a user.
+ * @function
+ * @param {import('express').Request} req - Express request object.
+ * @param {import('express').Response} res - Express response object.
+ * @param {import('express').NextFunction} next - Express next middleware function.
+ */
+const update = async (req, res, next) => {
+  try {
+    const message = UserServices.update();
+    res.status(constants.HTTP_STATUS_OK).json(message);
+  } catch (err) {
+    next(err);
+  }
+};
+
+/**
+ * Callback function for delete a user.
+ * @function
+ * @param {import('express').Request} req - Express request object.
+ * @param {import('express').Response} res - Express response object.
+ * @param {import('express').NextFunction} next - Express next middleware function.
+ */
+const drop = async (req, res, next) => {
+  try {
+    const message = UserServices.deleteByID();
+    res.status(constants.HTTP_STATUS_OK).json(message);
+  } catch (err) {
+    next(err);
+  }
+};
+
 export const UsersController = {
-  getById: (req, res, next) => {
-    try {
-      const message = UserServices.getById();
-      res.status(constants.HTTP_STATUS_OK).json(message);
-    } catch (err) {
-      next(err);
-    }
-  },
-  create: async (req, res, next) => {
-    try {
-      const message = UserServices.create();
-      res.status(constants.HTTP_STATUS_OK).json(message);
-    } catch (err) {
-      next(err);
-    }
-  },
-  update: async (req, res, next) => {
-    try {
-      const message = UserServices.update();
-      res.status(constants.HTTP_STATUS_OK).json(message);
-    } catch (err) {
-      next(err);
-    }
-  },
-  delete: async (req, res, next) => {
-    try {
-      const message = UserServices.deleteByID();
-      res.status(constants.HTTP_STATUS_OK).json(message);
-    } catch (err) {
-      next(err);
-    }
-  },
+  getById,
+  create,
+  update,
+  delete: drop,
 };

app/internal/core/domain/models/responses.models.js

@@ -1,6 +1,11 @@
+/**
+ * Auth middlewares
+ * @module Models/Responses
+ */
+
 /**
  * Represents a simple response object.
- * @typedef {Object} SimpleResponse
+ * @typedef {object} SimpleResponse
  * @property {string} message - The message associated with the response.
  */
 
@@ -15,7 +20,7 @@ const simple = (message) => ({
 
 /**
  * Represents a token response object.
- * @typedef {Object} TokenResponse
+ * @typedef {object} TokenResponse
  * @property {string} access_token - The token created.
  * @property {string} expires_in - The expiration time of the toke.
  * @property {string} tokenType - The token type for the request, by default is Bearer.
@@ -24,10 +29,9 @@ const simple = (message) => ({
 /**
  * Creates a token response object.
  * @param {string} token - The token created with the expiration time.
- * @property {string} expiresIn - The expiration time of the token.
+ * @param {string} expiresIn - The expiration time of the token.
  * @returns {TokenResponse} The token response with the information about the token created.
  */
-
 const tokenResponse = (token, expiresIn) => ({
   access_token: token,
   expiresIn,