From 21505d41921c321bfb60961bdb9a6f10cf0627a3 Mon Sep 17 00:00:00 2001 From: MekalaNagarajan-Centrica Date: Tue, 25 Jan 2022 13:20:12 +0000 Subject: [PATCH 1/3] chore: linting for jsdoc --- .eslintrc.js | 2 +- package-lock.json | 155 ++++++++++++++++++ package.json | 1 + .../components/cta/src/cta-component.js | 17 +- .../components/detail/src/detail-component.js | 1 + .../components/icon/src/icon-component.js | 2 +- .../components/image/src/image-component.js | 1 - .../inputter/src/inputter-component.js | 7 +- packages/library/mixins/detail-mixin.js | 8 +- packages/library/mixins/form-element-mixin.js | 28 +++- packages/library/mixins/mask-mixin.js | 10 +- packages/library/mixins/validation-mixin.js | 36 ++-- .../library/utils/validation-functions.js | 4 + 13 files changed, 237 insertions(+), 35 deletions(-) diff --git a/.eslintrc.js b/.eslintrc.js index 69e6893e..925a96a0 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -4,7 +4,7 @@ module.exports = { es6: true, node: true }, - extends: 'eslint:recommended', + extends: ['eslint:recommended', 'plugin:jsdoc/recommended'], parserOptions: { ecmaVersion: 2020, sourceType: 'module' diff --git a/package-lock.json b/package-lock.json index f3a4f27f..ca7ebc89 100644 --- a/package-lock.json +++ b/package-lock.json @@ -19,6 +19,7 @@ "@web/dev-server-storybook": "0.4.1", "@web/storybook-prebuilt": "0.1.33", "eslint": "8.7.0", + "eslint-plugin-jsdoc": "^37.6.3", "husky": "7.0.4", "npm-run-all": "4.1.5", "standard-version": "9.3.2", @@ -1947,6 +1948,20 @@ "node": ">=6.0.0" } }, + "node_modules/@es-joy/jsdoccomment": { + "version": "0.17.0", + "resolved": "https://registry.npmjs.org/@es-joy/jsdoccomment/-/jsdoccomment-0.17.0.tgz", + "integrity": "sha512-B8DIIWE194KyQFPojUs+THa2XX+1vulwTBjirw6GqcxjtNE60Rreex26svBnV9SNLTuz92ctZx5XQE1H7yOxgA==", + "dev": true, + "dependencies": { + "comment-parser": "1.3.0", + "esquery": "^1.4.0", + "jsdoc-type-pratt-parser": "~2.2.1" + }, + "engines": { + "node": "^12 || ^14 || ^16 || ^17" + } + }, "node_modules/@eslint/eslintrc": { "version": "1.0.5", "resolved": "https://registry.npmjs.org/@eslint/eslintrc/-/eslintrc-1.0.5.tgz", @@ -4408,6 +4423,15 @@ "node": ">= 6" } }, + "node_modules/comment-parser": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/comment-parser/-/comment-parser-1.3.0.tgz", + "integrity": "sha512-hRpmWIKgzd81vn0ydoWoyPoALEOnF4wt8yKD35Ib1D6XC2siLiYaiqfGkYrunuKdsXGwpBpHU3+9r+RVw2NZfA==", + "dev": true, + "engines": { + "node": ">= 12.0.0" + } + }, "node_modules/common-tags": { "version": "1.8.2", "license": "MIT", @@ -5521,6 +5545,57 @@ "url": "https://opencollective.com/eslint" } }, + "node_modules/eslint-plugin-jsdoc": { + "version": "37.6.3", + "resolved": "https://registry.npmjs.org/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-37.6.3.tgz", + "integrity": "sha512-Ysd1ZK4kL7DjjRJtWzb6Z7YANu7ndalu5PQBhOn07SlpKQ/+8JXvdtQ6yyADOO8w9xW5ZEEzuGY3KWhtk4CRYA==", + "dev": true, + "dependencies": { + "@es-joy/jsdoccomment": "~0.17.0", + "comment-parser": "1.3.0", + "debug": "^4.3.3", + "escape-string-regexp": "^4.0.0", + "esquery": "^1.4.0", + "regextras": "^0.8.0", + "semver": "^7.3.5", + "spdx-expression-parse": "^3.0.1" + }, + "engines": { + "node": "^12 || ^14 || ^16 || ^17" + }, + "peerDependencies": { + "eslint": "^7.0.0 || ^8.0.0" + } + }, + "node_modules/eslint-plugin-jsdoc/node_modules/debug": { + "version": "4.3.3", + "resolved": "https://registry.npmjs.org/debug/-/debug-4.3.3.tgz", + "integrity": "sha512-/zxw5+vh1Tfv+4Qn7a5nsbcJKPaSvCDhojn6FEl9vupwK2VCSDtEiEtqr8DFtzYFOdz63LBkxec7DYuc2jon6Q==", + "dev": true, + "dependencies": { + "ms": "2.1.2" + }, + "engines": { + "node": ">=6.0" + }, + "peerDependenciesMeta": { + "supports-color": { + "optional": true + } + } + }, + "node_modules/eslint-plugin-jsdoc/node_modules/escape-string-regexp": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz", + "integrity": "sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==", + "dev": true, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/eslint-scope": { "version": "7.1.0", "resolved": "https://registry.npmjs.org/eslint-scope/-/eslint-scope-7.1.0.tgz", @@ -7843,6 +7918,15 @@ "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==", "dev": true }, + "node_modules/jsdoc-type-pratt-parser": { + "version": "2.2.2", + "resolved": "https://registry.npmjs.org/jsdoc-type-pratt-parser/-/jsdoc-type-pratt-parser-2.2.2.tgz", + "integrity": "sha512-zRokSWcPLSWkoNzsWn9pq7YYSwDhKyEe+cJYT2qaPqLOOJb5sFSi46BPj81vP+e8chvCNdQL9RG86Bi9EI6MDw==", + "dev": true, + "engines": { + "node": ">=12.0.0" + } + }, "node_modules/jsesc": { "version": "2.5.2", "license": "MIT", @@ -10521,6 +10605,15 @@ "node": ">=4" } }, + "node_modules/regextras": { + "version": "0.8.0", + "resolved": "https://registry.npmjs.org/regextras/-/regextras-0.8.0.tgz", + "integrity": "sha512-k519uI04Z3SaY0fLX843MRXnDeG2+vHOFsyhiPZvNLe7r8rD2YNRjq4BQLZZ0oAr2NrtvZlICsXysGNFPGa3CQ==", + "dev": true, + "engines": { + "node": ">=0.1.14" + } + }, "node_modules/regjsgen": { "version": "0.5.2", "license": "MIT" @@ -17442,6 +17535,17 @@ "@csstools/convert-colors": { "version": "2.0.0" }, + "@es-joy/jsdoccomment": { + "version": "0.17.0", + "resolved": "https://registry.npmjs.org/@es-joy/jsdoccomment/-/jsdoccomment-0.17.0.tgz", + "integrity": "sha512-B8DIIWE194KyQFPojUs+THa2XX+1vulwTBjirw6GqcxjtNE60Rreex26svBnV9SNLTuz92ctZx5XQE1H7yOxgA==", + "dev": true, + "requires": { + "comment-parser": "1.3.0", + "esquery": "^1.4.0", + "jsdoc-type-pratt-parser": "~2.2.1" + } + }, "@eslint/eslintrc": { "version": "1.0.5", "resolved": "https://registry.npmjs.org/@eslint/eslintrc/-/eslintrc-1.0.5.tgz", @@ -20963,6 +21067,12 @@ "commander": { "version": "4.1.1" }, + "comment-parser": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/comment-parser/-/comment-parser-1.3.0.tgz", + "integrity": "sha512-hRpmWIKgzd81vn0ydoWoyPoALEOnF4wt8yKD35Ib1D6XC2siLiYaiqfGkYrunuKdsXGwpBpHU3+9r+RVw2NZfA==", + "dev": true + }, "common-tags": { "version": "1.8.2" }, @@ -21803,6 +21913,39 @@ } } }, + "eslint-plugin-jsdoc": { + "version": "37.6.3", + "resolved": "https://registry.npmjs.org/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-37.6.3.tgz", + "integrity": "sha512-Ysd1ZK4kL7DjjRJtWzb6Z7YANu7ndalu5PQBhOn07SlpKQ/+8JXvdtQ6yyADOO8w9xW5ZEEzuGY3KWhtk4CRYA==", + "dev": true, + "requires": { + "@es-joy/jsdoccomment": "~0.17.0", + "comment-parser": "1.3.0", + "debug": "^4.3.3", + "escape-string-regexp": "^4.0.0", + "esquery": "^1.4.0", + "regextras": "^0.8.0", + "semver": "^7.3.5", + "spdx-expression-parse": "^3.0.1" + }, + "dependencies": { + "debug": { + "version": "4.3.3", + "resolved": "https://registry.npmjs.org/debug/-/debug-4.3.3.tgz", + "integrity": "sha512-/zxw5+vh1Tfv+4Qn7a5nsbcJKPaSvCDhojn6FEl9vupwK2VCSDtEiEtqr8DFtzYFOdz63LBkxec7DYuc2jon6Q==", + "dev": true, + "requires": { + "ms": "2.1.2" + } + }, + "escape-string-regexp": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz", + "integrity": "sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==", + "dev": true + } + } + }, "eslint-scope": { "version": "7.1.0", "resolved": "https://registry.npmjs.org/eslint-scope/-/eslint-scope-7.1.0.tgz", @@ -23135,6 +23278,12 @@ } } }, + "jsdoc-type-pratt-parser": { + "version": "2.2.2", + "resolved": "https://registry.npmjs.org/jsdoc-type-pratt-parser/-/jsdoc-type-pratt-parser-2.2.2.tgz", + "integrity": "sha512-zRokSWcPLSWkoNzsWn9pq7YYSwDhKyEe+cJYT2qaPqLOOJb5sFSi46BPj81vP+e8chvCNdQL9RG86Bi9EI6MDw==", + "dev": true + }, "jsesc": { "version": "2.5.2" }, @@ -24835,6 +24984,12 @@ "unicode-match-property-value-ecmascript": "^2.0.0" } }, + "regextras": { + "version": "0.8.0", + "resolved": "https://registry.npmjs.org/regextras/-/regextras-0.8.0.tgz", + "integrity": "sha512-k519uI04Z3SaY0fLX843MRXnDeG2+vHOFsyhiPZvNLe7r8rD2YNRjq4BQLZZ0oAr2NrtvZlICsXysGNFPGa3CQ==", + "dev": true + }, "regjsgen": { "version": "0.5.2" }, diff --git a/package.json b/package.json index 1834fa57..6e2a6f2a 100644 --- a/package.json +++ b/package.json @@ -32,6 +32,7 @@ "@web/dev-server-storybook": "0.4.1", "@web/storybook-prebuilt": "0.1.33", "eslint": "8.7.0", + "eslint-plugin-jsdoc": "^37.6.3", "husky": "7.0.4", "npm-run-all": "4.1.5", "standard-version": "9.3.2", diff --git a/packages/library/components/cta/src/cta-component.js b/packages/library/components/cta/src/cta-component.js index 12b2261b..f01b7fb5 100644 --- a/packages/library/components/cta/src/cta-component.js +++ b/packages/library/components/cta/src/cta-component.js @@ -13,7 +13,6 @@ import styles from './styles.css'; * A call-to-action allows users to take action once they are ready for it. * * @element cta - * */ export class Cta extends ScopedElementsMixin(MuonElement) { @@ -51,10 +50,10 @@ export class Cta extends ScopedElementsMixin(MuonElement) { } /** - * @protected - * @description adds icon html - * @returns {HTMLElement} icon html - */ + * @protected + * @description adds icon html + * @returns {HTMLElement} icon html + */ get _addIcon() { let icon = this.loading ? CTA_LOADING_ICON_NAME : this.icon; @@ -72,10 +71,10 @@ export class Cta extends ScopedElementsMixin(MuonElement) { } /** - * @protected - * @param {string} content text content or slot element - * @returns {HTMLElement} cta shadow html - */ + * @protected + * @param {string} content text content or slot element + * @returns {HTMLElement} cta shadow html + */ _wrapperElement(content) { const parentElement = this.parentElement; const parentName = parentElement?.nodeName; diff --git a/packages/library/components/detail/src/detail-component.js b/packages/library/components/detail/src/detail-component.js index 92e1988b..5a4e8568 100644 --- a/packages/library/components/detail/src/detail-component.js +++ b/packages/library/components/detail/src/detail-component.js @@ -9,6 +9,7 @@ import { /** * A component to show and hide content related to a heading. + * * @element detail */ export class Detail extends DetailMixin(MuonElement) { diff --git a/packages/library/components/icon/src/icon-component.js b/packages/library/components/icon/src/icon-component.js index f34f63bc..12735528 100644 --- a/packages/library/components/icon/src/icon-component.js +++ b/packages/library/components/icon/src/icon-component.js @@ -14,7 +14,6 @@ import styles from './styles.css'; * Icons are visual symbols that are used to represent objects or actions to reduce cognitive load to a user. * * @element icon - * */ export class Icon extends MuonElement { @@ -49,6 +48,7 @@ export class Icon extends MuonElement { * * @readonly * @memberof Icon + * @returns {number[] | string } - all sizes defined or 100%. */ get sizes() { const size = this.size - 1; diff --git a/packages/library/components/image/src/image-component.js b/packages/library/components/image/src/image-component.js index ae9cdf2d..f6bae2db 100644 --- a/packages/library/components/image/src/image-component.js +++ b/packages/library/components/image/src/image-component.js @@ -13,7 +13,6 @@ import styles from './styles.css'; * Loading images with default lazy loading * * @element image - * */ export class Image extends MuonElement { diff --git a/packages/library/components/inputter/src/inputter-component.js b/packages/library/components/inputter/src/inputter-component.js index 9957f90c..583315d8 100644 --- a/packages/library/components/inputter/src/inputter-component.js +++ b/packages/library/components/inputter/src/inputter-component.js @@ -54,7 +54,8 @@ export class Inputter extends ScopedElementsMixin(MaskMixin(ValidationMixin(Muon /** * A method to check availability of tip details slot. - * @returns {Boolean} - availability of tip details slot. + * + * @returns {boolean} - availability of tip details slot. * @private */ get __isTipDetailAvailable() { @@ -63,7 +64,8 @@ export class Inputter extends ScopedElementsMixin(MaskMixin(ValidationMixin(Muon /** * A method to get helper template - * @returns {RenderTemplate} - helper template + * + * @returns {object} TemplateResult - helper template * @protected * @override */ @@ -114,6 +116,7 @@ export class Inputter extends ScopedElementsMixin(MaskMixin(ValidationMixin(Muon /** * InputterDetail component to handle helper text + * * @element inputter-detail * @private */ diff --git a/packages/library/mixins/detail-mixin.js b/packages/library/mixins/detail-mixin.js index abc810e9..0da461a0 100644 --- a/packages/library/mixins/detail-mixin.js +++ b/packages/library/mixins/detail-mixin.js @@ -3,6 +3,7 @@ import { Icon } from '@muons/library/components/icon'; /** * A mixin to hold show / hide content + * * @mixin */ @@ -51,6 +52,7 @@ export const DetailMixin = (superClass) => /** * A method to handle 'toggle' event from the html detail element. + * * @param {Event} toggleEvent - event to handle. * @returns {undefined} */ @@ -95,7 +97,8 @@ export const DetailMixin = (superClass) => /** * A method to render the heading part. - * @returns {RenderTemplate} - rendering template + * + * @returns {object} TemplateResult - rendering template */ _headingTemplate() { const isToggleStart = this._togglePosition === 'start'; @@ -110,7 +113,8 @@ export const DetailMixin = (superClass) => /** * A method to render the content part when expanded. - * @returns {RenderTemplate} - rendering template + * + * @returns {object} TemplateResult - rendering template */ _contentTemplate() { return html` diff --git a/packages/library/mixins/form-element-mixin.js b/packages/library/mixins/form-element-mixin.js index 420d6c75..d9165b9d 100644 --- a/packages/library/mixins/form-element-mixin.js +++ b/packages/library/mixins/form-element-mixin.js @@ -2,6 +2,7 @@ import { html, MuonElement } from '@muons/library'; /** * A mixin to hold base setup for a form element. + * * @mixin FormElementMixin */ @@ -66,6 +67,8 @@ export const FormElementMixin = (superClass) => /** * A method to generate random Id for html elements. + * + * @returns {string} - random generated id. * @protected */ get _randomId() { @@ -74,6 +77,7 @@ export const FormElementMixin = (superClass) => /** * A method to assign input type from the slotted html form elements. + * * @returns {undefined} * @private */ @@ -108,6 +112,7 @@ export const FormElementMixin = (superClass) => /** * A method to get all slotted HTML form elements. + * * @protected * @override */ @@ -118,6 +123,7 @@ export const FormElementMixin = (superClass) => /** * A method to get slotted label element. + * * @protected * @override */ @@ -127,6 +133,7 @@ export const FormElementMixin = (superClass) => /** * A method to determine if slotted form element has multiple option. + * * @protected * @override */ @@ -139,6 +146,7 @@ export const FormElementMixin = (superClass) => /** * A method to determine if slotted form element has only single option. + * * @protected * @override */ @@ -151,6 +159,7 @@ export const FormElementMixin = (superClass) => /** * A method to determine if slotted form element has only select option. + * * @protected * @override */ @@ -163,6 +172,7 @@ export const FormElementMixin = (superClass) => /** * A method to handle `change` event from the slotted html elements. + * * @protected * @override */ @@ -175,6 +185,7 @@ export const FormElementMixin = (superClass) => /** * A method to handle `blur` event from the slotted html elements. + * * @protected * @override */ @@ -184,6 +195,7 @@ export const FormElementMixin = (superClass) => /** * A method to fire the 'change' custom event from the form element. + * * @protected * @override */ @@ -197,8 +209,9 @@ export const FormElementMixin = (superClass) => /** * A method to remove whitespace from the form element value - * @param {String} value - form element value to be trimmed. - * @returns {String} - trimmed value + * + * @param {string} value - form element value to be trimmed. + * @returns {string} - trimmed value * @private */ __removeWhitespace(value) { @@ -207,8 +220,9 @@ export const FormElementMixin = (superClass) => /** * A method to process form element value before assigning to 'value' property - * @param {String} value - form elment value to be processed. - * @returns {String} - processed value + * + * @param {string} value - form elment value to be processed. + * @returns {string} - processed value * @protected * @override */ @@ -218,6 +232,8 @@ export const FormElementMixin = (superClass) => /** * A method to get values of checked form element. + * + * @returns {string[]} - array of selected values for multiple option input. * @private */ get __checkedInput() { @@ -230,6 +246,7 @@ export const FormElementMixin = (superClass) => /** * A method to get anonymous slot template to hold html form elements. + * * @protected * @override */ @@ -239,6 +256,7 @@ export const FormElementMixin = (superClass) => /** * A method to get label slot template to hold html form element label. + * * @protected * @override */ @@ -248,6 +266,7 @@ export const FormElementMixin = (superClass) => /** * A method to get heading slot template to hold html form element heading. + * * @protected * @override */ @@ -257,6 +276,7 @@ export const FormElementMixin = (superClass) => /** * A method to get standard template for type `standard`. + * * @protected * @override */ diff --git a/packages/library/mixins/mask-mixin.js b/packages/library/mixins/mask-mixin.js index 00fee662..aee86285 100644 --- a/packages/library/mixins/mask-mixin.js +++ b/packages/library/mixins/mask-mixin.js @@ -6,6 +6,7 @@ import { FormElementMixin } from './form-element-mixin'; * A mixin to enable mask and separator features to a form element. * `mask` property is supported for input of type text, date, tel. * `separator` property is supported for input of type text, date, tel. + * * @mixin */ @@ -43,6 +44,7 @@ export const MaskMixin = dedupeMixin((superclass) => /** * A method to handle `input` event when `mask` is provided. + * * @param {Event} inputEvent - event while 'input. * @returns {undefined} * @protected @@ -99,8 +101,8 @@ export const MaskMixin = dedupeMixin((superclass) => * A method to format the form element value with separator adjusted to correct indices * after editing the form element value. * - * @param {String} value - value of the form element. - * @return {String} - value with adjusted separator in correct indices. + * @param {string} value - value of the form element. + * @returns {string} - value with adjusted separator in correct indices. */ formatWithMaskAndSeparator(value) { const formattedValue = this.__formatInputWithoutSeparator(value); @@ -130,8 +132,8 @@ export const MaskMixin = dedupeMixin((superclass) => /** * A method to remove separator from the value of the form element. * - * @param {String} value - form element value. - * @return {String} - value with separator removed. + * @param {string} value - form element value. + * @returns {string} - value with separator removed. */ __formatInputWithoutSeparator(value) { return value.split(this.separator).join(''); diff --git a/packages/library/mixins/validation-mixin.js b/packages/library/mixins/validation-mixin.js index fb55f641..ec79aa8d 100644 --- a/packages/library/mixins/validation-mixin.js +++ b/packages/library/mixins/validation-mixin.js @@ -4,6 +4,7 @@ import { FormElementMixin } from './form-element-mixin'; /** * A mixin to hold the validation state of a form element. + * * @mixin */ @@ -59,7 +60,8 @@ export const ValidationMixin = (superClass) => /** * A method to add additional custom validations. - * @param {Object} validations - custom validation function name and definitions. + * + * @param {object} validations - custom validation function name and definitions. * @protected * @override */ @@ -73,6 +75,8 @@ export const ValidationMixin = (superClass) => /** * A getter method to get pristine state of the form element + * + * @returns {boolean} - pristine state */ get isPristine() { return this._pristine; @@ -80,6 +84,8 @@ export const ValidationMixin = (superClass) => /** * A getter method to get dirty state of the form element + * + * @returns {boolean} - dirty state */ get isDirty() { return !this._pristine; @@ -100,7 +106,7 @@ export const ValidationMixin = (superClass) => /** * A method to validate the value of the form element. - * @param {String} value - form element value to be validated. + * * @returns {ValidityState} - validity state of the form element. * @public * @override @@ -133,7 +139,8 @@ export const ValidationMixin = (superClass) => /** * A method to do native html form element validation. - * @returns {Object} - validation state + * + * @returns {object} - validation state * @private */ __validateNative() { @@ -159,8 +166,9 @@ export const ValidationMixin = (superClass) => /** * A method to parse the validation function name to return function name and parameter list (if any). - * @param {String} validation - validation function name. - * @returns {Object} - parsed function name and parameter list. + * + * @param {string} validation - validation function name. + * @returns {object} - parsed function name and parameter list. * @private */ __parseValidationFunction(validation) { @@ -186,7 +194,8 @@ export const ValidationMixin = (superClass) => /** * A method to update the custom validity of the html form elements. - * @param {String} validationMessage - validation message to be set + * + * @param {string} validationMessage - validation message to be set * @returns {undefined} * @private */ @@ -202,6 +211,7 @@ export const ValidationMixin = (superClass) => /** * A getter method to return warning icon of validation message. + * * @protected * @override * @readonly @@ -212,7 +222,8 @@ export const ValidationMixin = (superClass) => /** * A method to get a validation message combind from the validity states. - * @returns {String} - validation message + * + * @returns {string} - validation message * @private */ get __validationMessage() { @@ -225,7 +236,8 @@ export const ValidationMixin = (superClass) => /** * A method to get validation message template - * @returns {RenderTemplate} - validation message template + * + * @returns {object} TemplateResult - validation message template * @protected * @override */ @@ -245,7 +257,8 @@ export const ValidationMixin = (superClass) => /** * A method to get list view of validation message template - * @returns {RenderTemplate} - validation message template + * + * @returns {object} TemplateResult - validation message template * @protected * @override */ @@ -269,8 +282,9 @@ export const ValidationMixin = (superClass) => /** * A method to render each of validation state message template - * @param {String} key - validation function name - * @returns {RenderTemplate} validation template + * + * @param {string} key - validation function name + * @returns {object} TemplateResult validation template * @protected * @override */ diff --git a/packages/library/utils/validation-functions.js b/packages/library/utils/validation-functions.js index 51710b6a..fad40752 100644 --- a/packages/library/utils/validation-functions.js +++ b/packages/library/utils/validation-functions.js @@ -147,6 +147,10 @@ const maxDate = (inputter, value, max) => { return ''; }; +/** + * @param {string} value - value to check + * @returns {boolean} - true or false + */ function isNumeric(value) { const regex = /[^0-9]/g; return value && !value.match(regex); From 25ec65f17e55af414a8d58236db006e7bdd8242d Mon Sep 17 00:00:00 2001 From: MekalaNagarajan-Centrica Date: Thu, 27 Jan 2022 10:53:04 +0000 Subject: [PATCH 2/3] chore: lint rule error fixes --- .eslintrc.js | 28 ++++++++++++- .../components/cta/src/cta-component.js | 11 +++-- .../components/icon/src/icon-component.js | 5 +-- .../components/image/src/image-component.js | 2 +- .../inputter/src/inputter-component.js | 8 ++-- packages/library/mixins/detail-mixin.js | 11 ++--- packages/library/mixins/form-element-mixin.js | 18 ++++---- packages/library/mixins/mask-mixin.js | 16 ++++---- packages/library/mixins/validation-mixin.js | 41 ++++++++++--------- .../library/utils/validation-functions.js | 13 +++++- 10 files changed, 96 insertions(+), 57 deletions(-) diff --git a/.eslintrc.js b/.eslintrc.js index 925a96a0..285ad498 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -4,7 +4,8 @@ module.exports = { es6: true, node: true }, - extends: ['eslint:recommended', 'plugin:jsdoc/recommended'], + extends: ['eslint:recommended'], + plugins: ['jsdoc'], parserOptions: { ecmaVersion: 2020, sourceType: 'module' @@ -102,6 +103,29 @@ module.exports = { 'prefer-const': 'warn', 'space-before-function-paren': ['warn', { named: 'never' - }] + }], + 'jsdoc/check-alignment': 1, + 'jsdoc/check-indentation': 1, + 'jsdoc/check-param-names': 1, + 'jsdoc/check-syntax': 1, + 'jsdoc/check-types': 1, + 'jsdoc/implements-on-classes': 1, + 'jsdoc/match-description': 1, + 'jsdoc/newline-after-description': 1, + 'jsdoc/no-types': ['error' | 'warn', { contexts: ['any'] }], + 'jsdoc/no-undefined-types': 1, + 'jsdoc/require-description': 1, + 'jsdoc/require-description-complete-sentence': 1, + 'jsdoc/require-hyphen-before-param-description': 1, + 'jsdoc/require-jsdoc': 1, + 'jsdoc/require-param': 1, + 'jsdoc/require-param-description': 1, + 'jsdoc/require-param-name': 1, + 'jsdoc/require-param-type': 1, + 'jsdoc/require-returns': 1, + 'jsdoc/require-returns-check': 1, + 'jsdoc/require-returns-description': 1, + 'jsdoc/require-returns-type': 1, + 'jsdoc/valid-types': 1 } }; diff --git a/packages/library/components/cta/src/cta-component.js b/packages/library/components/cta/src/cta-component.js index f01b7fb5..81b4a33d 100644 --- a/packages/library/components/cta/src/cta-component.js +++ b/packages/library/components/cta/src/cta-component.js @@ -50,9 +50,10 @@ export class Cta extends ScopedElementsMixin(MuonElement) { } /** + * Adds icon html. + * + * @returns {object} TemplateResult - Icon html. * @protected - * @description adds icon html - * @returns {HTMLElement} icon html */ get _addIcon() { let icon = this.loading ? CTA_LOADING_ICON_NAME : this.icon; @@ -71,9 +72,11 @@ export class Cta extends ScopedElementsMixin(MuonElement) { } /** + * A method to wrap the cta content with button / a / div. + * + * @param {string | HTMLSlotElement} content - Text content or slot element. + * @returns {object} TemplateResult - Cta shadow html. * @protected - * @param {string} content text content or slot element - * @returns {HTMLElement} cta shadow html */ _wrapperElement(content) { const parentElement = this.parentElement; diff --git a/packages/library/components/icon/src/icon-component.js b/packages/library/components/icon/src/icon-component.js index 12735528..2db8300c 100644 --- a/packages/library/components/icon/src/icon-component.js +++ b/packages/library/components/icon/src/icon-component.js @@ -44,11 +44,10 @@ export class Icon extends MuonElement { } /** + * A getter method to get size of image. * - * + * @returns {number | string} - Size at specific index or 100%. * @readonly - * @memberof Icon - * @returns {number[] | string } - all sizes defined or 100%. */ get sizes() { const size = this.size - 1; diff --git a/packages/library/components/image/src/image-component.js b/packages/library/components/image/src/image-component.js index f6bae2db..c3b9426a 100644 --- a/packages/library/components/image/src/image-component.js +++ b/packages/library/components/image/src/image-component.js @@ -9,7 +9,7 @@ import { import styles from './styles.css'; -/** +/**. * Loading images with default lazy loading * * @element image diff --git a/packages/library/components/inputter/src/inputter-component.js b/packages/library/components/inputter/src/inputter-component.js index 583315d8..e5450734 100644 --- a/packages/library/components/inputter/src/inputter-component.js +++ b/packages/library/components/inputter/src/inputter-component.js @@ -55,7 +55,7 @@ export class Inputter extends ScopedElementsMixin(MaskMixin(ValidationMixin(Muon /** * A method to check availability of tip details slot. * - * @returns {boolean} - availability of tip details slot. + * @returns {boolean} - Availability of tip details slot. * @private */ get __isTipDetailAvailable() { @@ -63,9 +63,9 @@ export class Inputter extends ScopedElementsMixin(MaskMixin(ValidationMixin(Muon } /** - * A method to get helper template + * A method to get helper template. * - * @returns {object} TemplateResult - helper template + * @returns {object} TemplateResult - helper template. * @protected * @override */ @@ -114,7 +114,7 @@ export class Inputter extends ScopedElementsMixin(MaskMixin(ValidationMixin(Muon } } -/** +/**. * InputterDetail component to handle helper text * * @element inputter-detail diff --git a/packages/library/mixins/detail-mixin.js b/packages/library/mixins/detail-mixin.js index 0da461a0..5d2cf811 100644 --- a/packages/library/mixins/detail-mixin.js +++ b/packages/library/mixins/detail-mixin.js @@ -1,7 +1,7 @@ import { html, classMap, ScopedElementsMixin } from '@muons/library'; import { Icon } from '@muons/library/components/icon'; -/** +/**. * A mixin to hold show / hide content * * @mixin @@ -53,8 +53,9 @@ export const DetailMixin = (superClass) => /** * A method to handle 'toggle' event from the html detail element. * - * @param {Event} toggleEvent - event to handle. - * @returns {undefined} + * @param {Event} toggleEvent - Event to handle. + * @returns {void} + * @example */ _onToggle(toggleEvent) { const isOpen = !!toggleEvent.target.open; @@ -98,7 +99,7 @@ export const DetailMixin = (superClass) => /** * A method to render the heading part. * - * @returns {object} TemplateResult - rendering template + * @returns {object} TemplateResult - rendering template. */ _headingTemplate() { const isToggleStart = this._togglePosition === 'start'; @@ -114,7 +115,7 @@ export const DetailMixin = (superClass) => /** * A method to render the content part when expanded. * - * @returns {object} TemplateResult - rendering template + * @returns {object} TemplateResult - rendering template. */ _contentTemplate() { return html` diff --git a/packages/library/mixins/form-element-mixin.js b/packages/library/mixins/form-element-mixin.js index d9165b9d..7d313592 100644 --- a/packages/library/mixins/form-element-mixin.js +++ b/packages/library/mixins/form-element-mixin.js @@ -68,7 +68,7 @@ export const FormElementMixin = (superClass) => /** * A method to generate random Id for html elements. * - * @returns {string} - random generated id. + * @returns {string} - Random generated id. * @protected */ get _randomId() { @@ -78,7 +78,7 @@ export const FormElementMixin = (superClass) => /** * A method to assign input type from the slotted html form elements. * - * @returns {undefined} + * @returns {void} * @private */ __assignInputType() { @@ -208,10 +208,10 @@ export const FormElementMixin = (superClass) => } /** - * A method to remove whitespace from the form element value + * A method to remove whitespace from the form element value. * - * @param {string} value - form element value to be trimmed. - * @returns {string} - trimmed value + * @param {string} value - Form element value to be trimmed. + * @returns {string} - Trimmed value. * @private */ __removeWhitespace(value) { @@ -219,10 +219,10 @@ export const FormElementMixin = (superClass) => } /** - * A method to process form element value before assigning to 'value' property + * A method to process form element value before assigning to 'value' property. * - * @param {string} value - form elment value to be processed. - * @returns {string} - processed value + * @param {string} value - Form elment value to be processed. + * @returns {string} - Processed value. * @protected * @override */ @@ -233,7 +233,7 @@ export const FormElementMixin = (superClass) => /** * A method to get values of checked form element. * - * @returns {string[]} - array of selected values for multiple option input. + * @returns {string} - Array of selected values for multiple option input. * @private */ get __checkedInput() { diff --git a/packages/library/mixins/mask-mixin.js b/packages/library/mixins/mask-mixin.js index aee86285..e2f72041 100644 --- a/packages/library/mixins/mask-mixin.js +++ b/packages/library/mixins/mask-mixin.js @@ -45,8 +45,8 @@ export const MaskMixin = dedupeMixin((superclass) => /** * A method to handle `input` event when `mask` is provided. * - * @param {Event} inputEvent - event while 'input. - * @returns {undefined} + * @param {Event} inputEvent - Event while 'input. + * @returns {void} * @protected * @override */ @@ -73,8 +73,8 @@ export const MaskMixin = dedupeMixin((superclass) => /** * A method to update the form element value with separator in adjusted indices and cursor position. * - * @param {HTMLInputElement} input - HTMLInputElement value to be updated with seperators - * @returns {undefined} + * @param {HTMLElement} input - HTMLInputElement value to be updated with seperators. + * @returns {void} */ updateValue(input) { let value = input.value; @@ -101,8 +101,8 @@ export const MaskMixin = dedupeMixin((superclass) => * A method to format the form element value with separator adjusted to correct indices * after editing the form element value. * - * @param {string} value - value of the form element. - * @returns {string} - value with adjusted separator in correct indices. + * @param {string} value - Value of the form element. + * @returns {string} - Value with adjusted separator in correct indices. */ formatWithMaskAndSeparator(value) { const formattedValue = this.__formatInputWithoutSeparator(value); @@ -132,8 +132,8 @@ export const MaskMixin = dedupeMixin((superclass) => /** * A method to remove separator from the value of the form element. * - * @param {string} value - form element value. - * @returns {string} - value with separator removed. + * @param {string} value - Form element value. + * @returns {string} - Value with separator removed. */ __formatInputWithoutSeparator(value) { return value.split(this.separator).join(''); diff --git a/packages/library/mixins/validation-mixin.js b/packages/library/mixins/validation-mixin.js index ec79aa8d..0e202cd3 100644 --- a/packages/library/mixins/validation-mixin.js +++ b/packages/library/mixins/validation-mixin.js @@ -61,7 +61,7 @@ export const ValidationMixin = (superClass) => /** * A method to add additional custom validations. * - * @param {object} validations - custom validation function name and definitions. + * @param {object} validations - Custom validation function name and definitions. * @protected * @override */ @@ -74,18 +74,20 @@ export const ValidationMixin = (superClass) => } /** - * A getter method to get pristine state of the form element + * A getter method to get pristine state of the form element. * - * @returns {boolean} - pristine state + * @returns {boolean} - Pristine state. + * @public */ get isPristine() { return this._pristine; } /** - * A getter method to get dirty state of the form element + * A getter method to get dirty state of the form element. * - * @returns {boolean} - dirty state + * @returns {boolean} - Dirty state. + * @public */ get isDirty() { return !this._pristine; @@ -107,7 +109,7 @@ export const ValidationMixin = (superClass) => /** * A method to validate the value of the form element. * - * @returns {ValidityState} - validity state of the form element. + * @returns {ValidityState} - Validity state of the form element. * @public * @override */ @@ -140,7 +142,7 @@ export const ValidationMixin = (superClass) => /** * A method to do native html form element validation. * - * @returns {object} - validation state + * @returns {object} - Validation state. * @private */ __validateNative() { @@ -167,8 +169,8 @@ export const ValidationMixin = (superClass) => /** * A method to parse the validation function name to return function name and parameter list (if any). * - * @param {string} validation - validation function name. - * @returns {object} - parsed function name and parameter list. + * @param {string} validation - Validation function name. + * @returns {object} - Parsed function name and parameter list. * @private */ __parseValidationFunction(validation) { @@ -195,8 +197,8 @@ export const ValidationMixin = (superClass) => /** * A method to update the custom validity of the html form elements. * - * @param {string} validationMessage - validation message to be set - * @returns {undefined} + * @param {string} validationMessage - Validation message to be set. + * @returns {void} * @private */ __updateAllValidity(validationMessage) { @@ -223,7 +225,7 @@ export const ValidationMixin = (superClass) => /** * A method to get a validation message combind from the validity states. * - * @returns {string} - validation message + * @returns {string} - Validation message. * @private */ get __validationMessage() { @@ -235,9 +237,9 @@ export const ValidationMixin = (superClass) => } /** - * A method to get validation message template + * A method to get validation message template. * - * @returns {object} TemplateResult - validation message template + * @returns {object} TemplateResult - validation message template. * @protected * @override */ @@ -256,9 +258,9 @@ export const ValidationMixin = (superClass) => } /** - * A method to get list view of validation message template + * A method to get list view of validation message template. * - * @returns {object} TemplateResult - validation message template + * @returns {object} TemplateResult - validation message template. * @protected * @override */ @@ -281,10 +283,11 @@ export const ValidationMixin = (superClass) => } /** - * A method to render each of validation state message template + * A method to render each of validation state message template. * - * @param {string} key - validation function name - * @returns {object} TemplateResult validation template + * @param {string} key - Validation function name. + * @param {string} value - Validation state or message. + * @returns {object} TemplateResult validation template. * @protected * @override */ diff --git a/packages/library/utils/validation-functions.js b/packages/library/utils/validation-functions.js index fad40752..d0ab07df 100644 --- a/packages/library/utils/validation-functions.js +++ b/packages/library/utils/validation-functions.js @@ -148,8 +148,17 @@ const maxDate = (inputter, value, max) => { }; /** - * @param {string} value - value to check - * @returns {boolean} - true or false + * A function to check whether the value is numeric or not. + * + * @function + * @param {string} value - value to check. + * @returns {boolean} - True or false. + * @example + * // returns false + * isNumeric('abcd'); + * @example + * // returns true + * isNumeric('374'); */ function isNumeric(value) { const regex = /[^0-9]/g; From 3c4a42d34f90c727bcdd85d16b49458e095b84c2 Mon Sep 17 00:00:00 2001 From: MekalaNagarajan-Centrica Date: Thu, 27 Jan 2022 16:26:42 +0000 Subject: [PATCH 3/3] fix: update package --- package-lock.json | 35 +++++++++++++++++++---------------- 1 file changed, 19 insertions(+), 16 deletions(-) diff --git a/package-lock.json b/package-lock.json index a43e6882..f8768fc7 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1782,13 +1782,6 @@ "node": ">=12" } }, - "node_modules/@csstools/convert-colors": { - "version": "2.0.0", - "license": "CC0-1.0", - "engines": { - "node": ">=6.0.0" - } - }, "node_modules/@es-joy/jsdoccomment": { "version": "0.17.0", "resolved": "https://registry.npmjs.org/@es-joy/jsdoccomment/-/jsdoccomment-0.17.0.tgz", @@ -3424,11 +3417,6 @@ "dev": true, "license": "MIT" }, - "node_modules/argparse": { - "version": "2.0.1", - "dev": true, - "license": "Python-2.0" - }, "node_modules/array-back": { "version": "3.1.0", "license": "MIT", @@ -14946,6 +14934,17 @@ "@cspotcode/source-map-consumer": "0.8.0" } }, + "@es-joy/jsdoccomment": { + "version": "0.17.0", + "resolved": "https://registry.npmjs.org/@es-joy/jsdoccomment/-/jsdoccomment-0.17.0.tgz", + "integrity": "sha512-B8DIIWE194KyQFPojUs+THa2XX+1vulwTBjirw6GqcxjtNE60Rreex26svBnV9SNLTuz92ctZx5XQE1H7yOxgA==", + "dev": true, + "requires": { + "comment-parser": "1.3.0", + "esquery": "^1.4.0", + "jsdoc-type-pratt-parser": "~2.2.1" + } + }, "@eslint/eslintrc": { "version": "1.0.5", "dev": true, @@ -16268,10 +16267,6 @@ "version": "4.1.3", "dev": true }, - "argparse": { - "version": "2.0.1", - "dev": true - }, "array-back": { "version": "3.1.0" }, @@ -18694,6 +18689,14 @@ "dev": true, "requires": { "argparse": "^2.0.1" + }, + "dependencies": { + "argparse": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", + "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==", + "dev": true + } } }, "jsdoc-type-pratt-parser": {