diff --git a/.eslintrc.js b/.eslintrc.js index 69e6893e..285ad498 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -4,7 +4,8 @@ module.exports = { es6: true, node: true }, - extends: 'eslint: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/package-lock.json b/package-lock.json index a53bac65..f8768fc7 100644 --- a/package-lock.json +++ b/package-lock.json @@ -20,6 +20,7 @@ "@web/storybook-prebuilt": "0.1.33", "chromatic": "6.3.4", "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", @@ -1781,6 +1782,20 @@ "node": ">=12" } }, + "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", "dev": true, @@ -3402,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", @@ -4269,6 +4279,15 @@ "node": ">= 12" } }, + "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", @@ -5519,6 +5538,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", "dev": true, @@ -7399,6 +7469,21 @@ "js-yaml": "bin/js-yaml.js" } }, + "node_modules/js-yaml/node_modules/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 + }, + "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", @@ -10567,6 +10652,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" @@ -14840,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, @@ -16162,10 +16267,6 @@ "version": "4.1.3", "dev": true }, - "argparse": { - "version": "2.0.1", - "dev": true - }, "array-back": { "version": "3.1.0" }, @@ -16676,6 +16777,12 @@ "commander": { "version": "8.3.0" }, + "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" }, @@ -17466,6 +17573,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", "dev": true, @@ -18549,8 +18689,22 @@ "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": { + "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" }, @@ -20465,6 +20619,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 dc7e76b3..2f534b9d 100644 --- a/package.json +++ b/package.json @@ -34,6 +34,7 @@ "@web/storybook-prebuilt": "0.1.33", "chromatic": "6.3.4", "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..81b4a33d 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,11 @@ export class Cta extends ScopedElementsMixin(MuonElement) { } /** - * @protected - * @description adds icon html - * @returns {HTMLElement} icon html - */ + * Adds icon html. + * + * @returns {object} TemplateResult - Icon html. + * @protected + */ get _addIcon() { let icon = this.loading ? CTA_LOADING_ICON_NAME : this.icon; @@ -72,10 +72,12 @@ export class Cta extends ScopedElementsMixin(MuonElement) { } /** - * @protected - * @param {string} content text content or slot element - * @returns {HTMLElement} cta shadow html - */ + * 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 + */ _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..2db8300c 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 { @@ -45,10 +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 */ 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..c3b9426a 100644 --- a/packages/library/components/image/src/image-component.js +++ b/packages/library/components/image/src/image-component.js @@ -9,11 +9,10 @@ import { 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 fc853ae6..1b148bb6 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() { @@ -62,8 +63,9 @@ export class Inputter extends ScopedElementsMixin(MaskMixin(ValidationMixin(Muon } /** - * A method to get helper template - * @returns {RenderTemplate} - helper template + * A method to get helper template. + * + * @returns {object} TemplateResult - helper template. * @protected * @override */ @@ -112,8 +114,9 @@ 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 a1f5ae5f..0355eb4c 100644 --- a/packages/library/mixins/detail-mixin.js +++ b/packages/library/mixins/detail-mixin.js @@ -1,8 +1,9 @@ import { html, classMap, ScopedElementsMixin, dedupeMixin } from '@muons/library'; import { Icon } from '@muons/library/components/icon'; -/** +/**. * A mixin to hold show / hide content + * * @mixin */ @@ -51,8 +52,10 @@ export const DetailMixin = dedupeMixin((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; @@ -95,7 +98,8 @@ export const DetailMixin = dedupeMixin((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 +114,8 @@ export const DetailMixin = dedupeMixin((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 1c1d0775..9d9352ba 100644 --- a/packages/library/mixins/form-element-mixin.js +++ b/packages/library/mixins/form-element-mixin.js @@ -2,6 +2,7 @@ import { html, MuonElement, dedupeMixin } from '@muons/library'; /** * A mixin to hold base setup for a form element. + * * @mixin FormElementMixin */ @@ -66,6 +67,8 @@ export const FormElementMixin = dedupeMixin((superClass) => /** * A method to generate random Id for html elements. + * + * @returns {string} - Random generated id. * @protected */ get _randomId() { @@ -74,7 +77,8 @@ export const FormElementMixin = dedupeMixin((superClass) => /** * A method to assign input type from the slotted html form elements. - * @returns {undefined} + * + * @returns {void} * @private */ __assignInputType() { @@ -108,6 +112,7 @@ export const FormElementMixin = dedupeMixin((superClass) => /** * A method to get all slotted HTML form elements. + * * @protected * @override */ @@ -118,6 +123,7 @@ export const FormElementMixin = dedupeMixin((superClass) => /** * A method to get slotted label element. + * * @protected * @override */ @@ -127,6 +133,7 @@ export const FormElementMixin = dedupeMixin((superClass) => /** * A method to determine if slotted form element has multiple option. + * * @protected * @override */ @@ -139,6 +146,7 @@ export const FormElementMixin = dedupeMixin((superClass) => /** * A method to determine if slotted form element has only single option. + * * @protected * @override */ @@ -151,6 +159,7 @@ export const FormElementMixin = dedupeMixin((superClass) => /** * A method to determine if slotted form element has only select option. + * * @protected * @override */ @@ -163,6 +172,7 @@ export const FormElementMixin = dedupeMixin((superClass) => /** * A method to handle `change` event from the slotted html elements. + * * @protected * @override */ @@ -175,6 +185,7 @@ export const FormElementMixin = dedupeMixin((superClass) => /** * A method to handle `blur` event from the slotted html elements. + * * @protected * @override */ @@ -184,6 +195,7 @@ export const FormElementMixin = dedupeMixin((superClass) => /** * A method to fire the 'change' custom event from the form element. + * * @protected * @override */ @@ -196,9 +208,10 @@ export const FormElementMixin = dedupeMixin((superClass) => } /** - * A method to remove whitespace from the form element value - * @param {String} value - form element value to be trimmed. - * @returns {String} - trimmed value + * A method to remove whitespace from the form element value. + * + * @param {string} value - Form element value to be trimmed. + * @returns {string} - Trimmed value. * @private */ __removeWhitespace(value) { @@ -206,9 +219,10 @@ export const FormElementMixin = dedupeMixin((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 + * 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. * @protected * @override */ @@ -218,6 +232,8 @@ export const FormElementMixin = dedupeMixin((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 = dedupeMixin((superClass) => /** * A method to get anonymous slot template to hold html form elements. + * * @protected * @override */ @@ -239,6 +256,7 @@ export const FormElementMixin = dedupeMixin((superClass) => /** * A method to get label slot template to hold html form element label. + * * @protected * @override */ @@ -248,6 +266,7 @@ export const FormElementMixin = dedupeMixin((superClass) => /** * A method to get heading slot template to hold html form element heading. + * * @protected * @override */ @@ -257,6 +276,7 @@ export const FormElementMixin = dedupeMixin((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 8510f829..d22c8151 100644 --- a/packages/library/mixins/mask-mixin.js +++ b/packages/library/mixins/mask-mixin.js @@ -5,6 +5,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 */ @@ -42,8 +43,9 @@ 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 */ @@ -70,8 +72,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; @@ -98,8 +100,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); @@ -129,8 +131,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 aa7d5f37..4bbc4994 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 = dedupeMixin((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 */ @@ -72,14 +74,20 @@ export const ValidationMixin = dedupeMixin((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. + * @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. + * @public */ get isDirty() { return !this._pristine; @@ -100,8 +108,8 @@ export const ValidationMixin = dedupeMixin((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. + * + * @returns {ValidityState} - Validity state of the form element. * @public * @override */ @@ -133,7 +141,8 @@ export const ValidationMixin = dedupeMixin((superClass) => /** * A method to do native html form element validation. - * @returns {Object} - validation state + * + * @returns {object} - Validation state. * @private */ __validateNative() { @@ -159,8 +168,9 @@ export const ValidationMixin = dedupeMixin((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,8 +196,9 @@ export const ValidationMixin = dedupeMixin((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) { @@ -202,6 +213,7 @@ export const ValidationMixin = dedupeMixin((superClass) => /** * A getter method to return warning icon of validation message. + * * @protected * @override * @readonly @@ -212,7 +224,8 @@ export const ValidationMixin = dedupeMixin((superClass) => /** * A method to get a validation message combind from the validity states. - * @returns {String} - validation message + * + * @returns {string} - Validation message. * @private */ get __validationMessage() { @@ -224,8 +237,9 @@ export const ValidationMixin = dedupeMixin((superClass) => } /** - * A method to get validation message template - * @returns {RenderTemplate} - validation message template + * A method to get validation message template. + * + * @returns {object} TemplateResult - validation message template. * @protected * @override */ @@ -244,8 +258,9 @@ export const ValidationMixin = dedupeMixin((superClass) => } /** - * A method to get list view of validation message template - * @returns {RenderTemplate} - validation message template + * A method to get list view of validation message template. + * + * @returns {object} TemplateResult - validation message template. * @protected * @override */ @@ -268,9 +283,11 @@ export const ValidationMixin = dedupeMixin((superClass) => } /** - * A method to render each of validation state message template - * @param {String} key - validation function name - * @returns {RenderTemplate} validation template + * A method to render each of validation state message 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 51710b6a..d0ab07df 100644 --- a/packages/library/utils/validation-functions.js +++ b/packages/library/utils/validation-functions.js @@ -147,6 +147,19 @@ const maxDate = (inputter, value, max) => { return ''; }; +/** + * 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; return value && !value.match(regex);