fix(build): eslint, jsdoc updates (#163)

cdcabrera · Aug 4, 2022 · dd20d53 · dd20d53
1 parent e5c456e
commit dd20d53
Show file tree

Hide file tree

Showing 8 changed files with 117 additions and 88 deletions.
diff --git a/.eslintrc b/.eslintrc
@@ -1,30 +1,65 @@
 {
-  "parser": "@babel/eslint-parser",
   "env": {
-    "es6": true,
+    "es2020": true,
     "jest": true,
     "node": true
   },
   "plugins": [
     "jest",
+    "jsdoc",
     "node",
     "prettier"
   ],
   "extends": [
     "eslint:recommended",
+    "plugin:jsdoc/recommended",
     "plugin:jest/recommended",
     "plugin:node/recommended",
     "plugin:prettier/recommended"
   ],
   "parserOptions":{
-    "ecmaVersion": 2018
+    "ecmaVersion": 2020
   },
   "rules": {
     "arrow-parens": [
       "error",
       "as-needed"
     ],
     "comma-dangle": 0,
+    "jsdoc/check-tag-names": [
+      2,
+      {
+        "definedTags": [
+          "api",
+          "apiDescription",
+          "apiHeader",
+          "apiSuccess",
+          "apiSuccessExample",
+          "apiError",
+          "apiErrorExample",
+          "apiMock",
+          "apiParam"
+        ]
+      }
+    ],
+    "jsdoc/no-undefined-types": [
+      1,
+      {
+        "definedTypes": [
+          "delete",
+          "get",
+          "html",
+          "json",
+          "patch",
+          "post",
+          "put",
+          "RandomResponse"
+        ]
+      }
+    ],
+    "jsdoc/require-param-description": 0,
+    "jsdoc/require-property-description": 0,
+    "jsdoc/require-returns-description": 0,
     "max-len": [
       "error",
       {

diff --git a/data/example.js b/data/example.js
@@ -1,8 +1,8 @@
 /**
  * @api {get} /hello/world/
  * @apiMock {RandomResponse}
- * @apiSuccess {String} foo
- * @apiSuccess {String} bar
+ * @apiSuccess {string} foo
+ * @apiSuccess {string} bar
  * @apiSuccessExample {json} Success-Response:
  *     HTTP/1.1 200 OK
  *     {
@@ -15,8 +15,8 @@
  *       "lorem": "dolor",
  *       "ipsum": "est"
  *     }
- * @apiError {String} bad
- * @apiError {String} request
+ * @apiError {string} bad
+ * @apiError {string} request
  * @apiErrorExample {json} Error-Response:
  *     HTTP/1.1 400 OK
  *     {
@@ -29,16 +29,16 @@ const getExample = () => {};
 /**
  * @api {post} /hello/world/
  * @apiMock {RandomResponse}
- * @apiHeader {String} Authorization Authorization: Token AUTH_TOKEN
- * @apiSuccess {String} foo
- * @apiSuccess {String} bar
+ * @apiHeader {string} Authorization Authorization: Token AUTH_TOKEN
+ * @apiSuccess {string} foo
+ * @apiSuccess {string} bar
  * @apiSuccessExample {json} Success-Response:
  *     HTTP/1.1 201 OK
  *     {
  *       "foo": "hello",
  *       "bar": "world"
  *     }
- * @apiError {String} detail
+ * @apiError {string} detail
  * @apiErrorExample {json} Error-Response:
  *     HTTP/1.1 401 Unauthorized
  *     {
@@ -49,9 +49,9 @@ const postExample = () => {};
 
 /**
  * @api {put} /hello/world/
- * @apiHeader {String} Authorization Authorization: Token AUTH_TOKEN
- * @apiSuccess {String} foo
- * @apiSuccess {String} bar
+ * @apiHeader {string} Authorization Authorization: Token AUTH_TOKEN
+ * @apiSuccess {string} foo
+ * @apiSuccess {string} bar
  * @apiSuccessExample {json} Success-Response:
  *     HTTP/1.1 200 OK
  *     {
@@ -63,9 +63,9 @@ const putExample = () => {};
 
 /**
  * @api {patch} /hello/world/
- * @apiHeader {String} Authorization Authorization: Token AUTH_TOKEN
- * @apiSuccess {String} foo
- * @apiSuccess {String} bar
+ * @apiHeader {string} Authorization Authorization: Token AUTH_TOKEN
+ * @apiSuccess {string} foo
+ * @apiSuccess {string} bar
  * @apiSuccessExample {json} Success-Response:
  *     HTTP/1.1 200 OK
  *     {
@@ -77,9 +77,9 @@ const patchExample = () => {};
 
 /**
  * @api {delete} /hello/world/
- * @apiHeader {String} Authorization Authorization: Token AUTH_TOKEN
- * @apiSuccess {String} foo
- * @apiSuccess {String} bar
+ * @apiHeader {string} Authorization Authorization: Token AUTH_TOKEN
+ * @apiSuccess {string} foo
+ * @apiSuccess {string} bar
  * @apiSuccessExample {json} Success-Response:
  *     HTTP/1.1 200 OK
  *     {

diff --git a/package.json b/package.json
@@ -32,7 +32,7 @@
     "test:dev": "rm -rf ./.docs; eslint ./src; jest --watch",
     "test:integration": "jest --roots=./tests",
     "test:integration-dev": "jest --roots=./tests --watchAll",
-    "test:lint": "eslint ./src ./bin"
+    "test:lint": "eslint ./src ./bin ./data"
   },
   "jest": {
     "roots": [
@@ -92,14 +92,12 @@
     "yargs": "^17.5.1"
   },
   "devDependencies": {
-    "@babel/eslint-parser": "^7.18.9",
     "eslint": "^8.21.0",
-    "eslint-config-esnext": "^4.1.0",
-    "eslint-config-node": "^4.1.0",
     "eslint-config-prettier": "^8.5.0",
     "eslint-plugin-babel": "^5.3.1",
     "eslint-plugin-import": "^2.26.0",
     "eslint-plugin-jest": "^26.7.0",
+    "eslint-plugin-jsdoc": "^39.3.4",
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-prettier": "^4.2.1",
     "jest": "^28.1.3",

diff --git a/src/api/buildApi.js b/src/api/buildApi.js
@@ -12,7 +12,7 @@ const {
  *
  * @param {object} request
  * @param {object} response
- * @param {function} next
+ * @param {Function} next
  */
 const buildRequestHeaders = (request, response, next) => {
   const hasOrigin = request.headers.origin != null;
@@ -37,8 +37,8 @@ const buildRequestHeaders = (request, response, next) => {
 /**
  * Build API response
  *
- * @param {array} apiJson
- * @returns {{app:array, routesLoaded: boolean}}
+ * @param {Array} apiJson
+ * @returns {{app:Array, routesLoaded: boolean}}
  */
 const buildResponse = (apiJson = []) => {
   const appResponses = [];

diff --git a/src/api/parseApi.js b/src/api/parseApi.js
@@ -4,9 +4,9 @@ const { logger } = require('../logger/configLogger');
  * Return forced response, or a general example.
  *
  * @param {object} mockSettings
- * @param {array} exampleObjects
- * @param {array} successObjects
- * @param {array} errorObjects
+ * @param {Array} exampleObjects
+ * @param {Array} successObjects
+ * @param {Array} errorObjects
  * @returns {{type: string, status: number, content: string}}
  */
 const exampleResponse = (mockSettings, exampleObjects, successObjects, errorObjects) => {
@@ -73,7 +73,7 @@ const exampleResponse = (mockSettings, exampleObjects, successObjects, errorObje
 /**
  * Return a 401 specific example.
  *
- * @param {array} errorObjects
+ * @param {Array} errorObjects
  * @returns {{type: string, status: number, content: string}}
  */
 const parseAuthExample = (errorObjects = []) => {
@@ -85,7 +85,8 @@ const parseAuthExample = (errorObjects = []) => {
 /**
  * Parse custom mock settings.
  *
- * @param {Object} mock
+ * @param {object} params
+ * @param {object} params.mock
  * @returns {object}
  */
 const parseCustomMockSettings = ({ mock = null }) => {
@@ -142,7 +143,7 @@ const parseCustomMockSettings = ({ mock = null }) => {
 /**
  * Set http status
  *
- * @param {array} examples
+ * @param {Array} examples
  * @param {string} response
  * @param {string} type
  * @param {string} path

diff --git a/src/docs/buildDocs.js b/src/docs/buildDocs.js
@@ -5,8 +5,9 @@ const { logger } = require('../logger/configLogger');
 /**
  * Compile/build ApiDoc documentation.
  *
- * @param {object} apiDocsConfig
- * @param {string} apiJsonFile
+ * @param {object} params
+ * @param {object} params.apiDocsConfig
+ * @param {string} params.apiJsonFile
  * @returns {object}
  */
 const buildDocs = ({ apiDocsConfig = null, apiJsonFile = null }) => {

diff --git a/src/index.js b/src/index.js
@@ -43,7 +43,7 @@ const setupDocs = (dataPath = '', docsPath = '') => {
 /**
  * Build response
  *
- * @param {array} apiJson
+ * @param {Array} apiJson
  * @param {number} port
  * @returns {*}
  */
@@ -67,9 +67,10 @@ const setupResponse = (apiJson = [], port) => {
 /**
  * ApiDocMock
  *
- * @param {number} port
- * @param {(string|string[])} dataPath
- * @param {string} docsPath
+ * @param {object} params
+ * @param {number} params.port
+ * @param {(string|string[])} params.dataPath
+ * @param {string} params.docsPath
  * @returns {*}
  */
 const apiDocMock = ({ port = 8000, dataPath, docsPath = '.docs' }) => {