chore: add eslint-plugin-jsdoc

Author: dukeluo

.eslintrc.js

@@ -7,8 +7,9 @@ module.exports = {
     'plugin:eslint-plugin/recommended',
     'plugin:node/recommended',
     'prettier',
+    'plugin:jsdoc/recommended',
   ],
-  plugins: ['prettier'],
+  plugins: ['prettier', 'jsdoc'],
   rules: {
     'prettier/prettier': 'error',
   },

lib/constants/naming-convention.js

@@ -1,5 +1,5 @@
 /**
- * @fileoverview Built in filename naming convention
+ * @file Built in filename naming convention
  * @author Duke Luo
  */
 'use strict';

lib/index.js

@@ -1,5 +1,5 @@
 /**
- * @fileoverview check the file folder
+ * @file check the file folder
  * @author Duke Luo
  */
 'use strict';

lib/rules/filename-blacklist.js

@@ -1,5 +1,5 @@
 /**
- * @fileoverview The filename should not be blacklisted.
+ * @file The filename should not be blacklisted.
  * @author Florian Ehmke
  */
 'use strict';
@@ -9,8 +9,9 @@ const { checkSettings, globPatternValidator } = require('../utils/settings');
 const { getDocUrl } = require('../utils/doc');
 const { matchRule } = require('../utils/match');
 
+/** @typedef {module:eslint} ESLint */
 /**
- * @type {import('eslint').Rule.RuleModule}
+ * @type {ESLint.Rule.RuleModule}
  */
 module.exports = {
   meta: {

lib/rules/filename-naming-convention.js

@@ -1,5 +1,5 @@
 /**
- * @fileoverview The filename should follow the filename naming convention
+ * @file The filename should follow the filename naming convention
  * @author Duke Luo
  */
 'use strict';
@@ -13,8 +13,9 @@ const {
 const { getDocUrl } = require('../utils/doc');
 const { matchRule } = require('../utils/match');
 
+/** @typedef {module:eslint} ESLint */
 /**
- * @type {import('eslint').Rule.RuleModule}
+ * @type {ESLint.Rule.RuleModule}
  */
 module.exports = {
   meta: {

lib/rules/folder-match-with-fex.js

@@ -1,5 +1,5 @@
 /**
- * @fileoverview The folder should match the naming pattern specified by the file extension
+ * @file The folder should match the naming pattern specified by the file extension
  * @author Duke Luo
  */
 'use strict';
@@ -13,8 +13,9 @@ const { checkSettings, globPatternValidator } = require('../utils/settings');
 const { getDocUrl } = require('../utils/doc');
 const { matchRule } = require('../utils/match');
 
+/** @typedef {module:eslint} ESLint */
 /**
- * @type {import('eslint').Rule.RuleModule}
+ * @type {ESLint.Rule.RuleModule}
  */
 module.exports = {
   meta: {

lib/rules/folder-naming-convention.js

@@ -1,5 +1,5 @@
 /**
- * @fileoverview The folder should follow the folder naming convention
+ * @file The folder should follow the folder naming convention
  * @author Duke Luo
  */
 'use strict';
@@ -19,8 +19,9 @@ const {
 const { getDocUrl } = require('../utils/doc');
 const NAMING_CONVENTION = require('../constants/naming-convention');
 
+/** @typedef {module:eslint} ESLint */
 /**
- * @type {import('eslint').Rule.RuleModule}
+ * @type {ESLint.Rule.RuleModule}
  */
 module.exports = {
   meta: {

lib/rules/no-index.js

@@ -1,14 +1,15 @@
 /**
- * @fileoverview A file cannot be named "index"
+ * @file A file cannot be named "index"
  * @author Duke Luo
  */
 'use strict';
 
 const { getDocUrl } = require('../utils/doc');
 const { getFilename, getBasename, getFilePath } = require('../utils/filename');
 
+/** @typedef {module:eslint} ESLint */
 /**
- * @type {import('eslint').Rule.RuleModule}
+ * @type {ESLint.Rule.RuleModule}
  */
 module.exports = {
   meta: {

lib/utils/doc.js

@@ -1,11 +1,11 @@
 /**
- * @fileoverview Utils about document
+ * @file Utils about document
  * @author Duke Luo
  */
 'use strict';
 
 /**
- * @type {string} rule document url
+ * @returns {string} rule document url
  * @param {string} rule rule name
  */
 const getDocUrl = (rule) =>

lib/utils/filename.js

@@ -1,26 +1,26 @@
 /**
- * @fileoverview Utils about filename
+ * @file Utils about filename
  * @author Duke Luo
  */
 'use strict';
 
 const path = require('path');
 
 /**
- * @type {string} filename without path
+ * @returns {string} filename without path
  * @param {string} p filename concat with path in posix style
  */
 const getFilename = (p) => path.posix.basename(p);
 
 /**
- * @type {string} path of folder
+ * @returns {string} path of folder
  * @param {string} p filename concat with path in posix style
  */
 const getFolderPath = (p) =>
   path.posix.join(path.posix.dirname(p), path.posix.sep);
 
 /**
- * @type {string} base name
+ * @returns {string} base name
  * @param {string} filename filename without path
  * @param {boolean} [ignoreMiddleExtensions=false] flag to ignore middle extensions
  */
@@ -31,14 +31,14 @@ const getBasename = (filename, ignoreMiddleExtensions = false) =>
   );
 
 /**
- * @type {string[]} all folders
+ * @returns {string[]} all folders
  * @param {string} p path of folder in posix style
  */
 const getAllFolders = (p) =>
   p.split(path.posix.sep).filter((folder) => folder !== '');
 
 /**
- * @type {string[]} all sub paths
+ * @returns {string[]} all sub paths
  * @param {string} p path of folder in posix style
  */
 const getSubPaths = (p) => {
@@ -65,42 +65,44 @@ const getSubPaths = (p) => {
 };
 
 /**
- * @type {string} path from repository root
+ * @returns {string} path from repository root
  * @param {string} fullPath filename with full path
  * @param {string} repositoryRoot path of repository root
  */
 const getPathFromRepositoryRoot = (fullPath, repositoryRoot) =>
   fullPath.replace(path.join(repositoryRoot, path.sep), '');
 
 /**
- * @type {string} file path in posix style
+ * @returns {string} file path in posix style
  * @param {string} p file path based on the operating system
  */
 const toPosixPath = (p) => p.split(path.sep).join(path.posix.sep);
 
 /**
- * @type {string} file path without drive letter on windows
+ * @returns {string} file path without drive letter on windows
  * @param {string} p file path on windows
  */
 const removeDriveLetter = (p) => p.replace(/^[A-Za-z]:\\/, '');
 
 /**
  * Callback for file path
+ *
  * @callback callback
  * @param {string} p file path
  */
 /**
- * @type {callback} piped function
+ * @returns {callback} piped function
  * @param {callback[]} fns callback functions
  */
 const pipe =
   (...fns) =>
   (x) =>
     fns.reduce((v, f) => f(v), x);
 
+/** @typedef {module:eslint} ESLint */
 /**
- * @type {string} file path in posix style
- * @param {Rule.RuleContext} context rule eslint context
+ * @returns {string} file path in posix style
+ * @param {ESLint.Rule.RuleContext} context rule eslint context
  */
 const getFilePath = (context) => {
   const pathFromRoot = getPathFromRepositoryRoot(

lib/utils/match.js

@@ -1,5 +1,5 @@
 /**
- * @fileoverview Utils about matching rule
+ * @file Utils about matching rule
  * @author Duke Luo
  */
 'use strict';
@@ -8,11 +8,11 @@ const micromatch = require('micromatch');
 const NAMING_CONVENTION = require('../constants/naming-convention');
 
 /**
- * @type {object | undefined} undefined or object with non-matching file path and naming pattern
- * @param filePath
- * @param targetFilePathPattern
- * @param targetNaming
- * @param targetNamingPattern
+ * @returns {object | undefined} undefined or object with non-matching file path and naming pattern
+ * @param {string} filePath file path
+ * @param {string} targetFilePathPattern path pattern of the target file
+ * @param {string} [targetNaming] target naming
+ * @param {string} [targetNamingPattern] naming pattern of the target naming
  */
 const matchRule = (
   filePath,

lib/utils/settings.js

@@ -1,5 +1,5 @@
 /**
- * @fileoverview Utils about rule settings
+ * @file Utils about rule settings
  * @author Duke Luo
  */
 'use strict';
@@ -8,10 +8,16 @@ const isGlob = require('is-glob');
 const NAMING_CONVENTION = require('../constants/naming-convention');
 
 /**
- * @type {string} invalid key or value
- * @param settings rule settings configurated by user
- * @param keyValidator settings key validator
- * @param valueValidator settings value validator
+ * Validator
+ *
+ * @callback validator
+ * @param {string} p pattern string
+ */
+/**
+ * @returns {string | undefined} undefined or invalid field
+ * @param {object} settings rule settings configurated by user
+ * @param {validator} keyValidator settings key validator
+ * @param {validator} valueValidator settings value validator
  */
 const checkSettings = (settings, keyValidator, valueValidator) => {
   for (const [key, value] of Object.entries(settings)) {
@@ -24,8 +30,8 @@ const checkSettings = (settings, keyValidator, valueValidator) => {
 };
 
 /**
- * @type {boolean}
- * @param namingPattern pattern string
+ * @returns {boolean} true if pattern is a valid naming pattern
+ * @param {string} namingPattern pattern string
  */
 const namingPatternValidator = (namingPattern) => {
   const buildInPatterns = Object.keys(NAMING_CONVENTION);
@@ -34,8 +40,8 @@ const namingPatternValidator = (namingPattern) => {
 };
 
 /**
- * @type {boolean}
- * @param pattern pattern string
+ * @returns {boolean} true if pattern is a valid glob pattern
+ * @param {string} pattern pattern string
  */
 const globPatternValidator = isGlob;