diff --git a/.eslintrc.js b/.eslintrc.js index df068352b94..86145d9cbb1 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -50,6 +50,27 @@ module.exports = defineConfig({ '@typescript-eslint/unbound-method': 'warn', }, overrides: [ + { + files: ['src/**/*.ts'], + plugins: ['jsdoc'], + extends: ['plugin:jsdoc/recommended'], + rules: { + 'jsdoc/no-types': 'error', + 'jsdoc/require-param-type': 'off', + 'jsdoc/require-returns-type': 'off', + 'jsdoc/require-returns': 'off', + 'jsdoc/tag-lines': 'off', + + // Rule will come in one of the next releases: https://github.com/gajus/eslint-plugin-jsdoc/pull/833 + // We want to explicitly set this rule to error in the future + // 'jsdoc/sort-tags': 'warn', + }, + settings: { + jsdoc: { + mode: 'typescript', + }, + }, + }, { files: ['test/*.spec.ts'], rules: { diff --git a/package.json b/package.json index 3e37153a77d..41623ed4c59 100644 --- a/package.json +++ b/package.json @@ -87,7 +87,7 @@ ] }, "devDependencies": { - "@types/node": "~16.11.21", + "@types/node": "~16.11.22", "@typescript-eslint/eslint-plugin": "~5.10.2", "@typescript-eslint/parser": "~5.10.2", "@types/prettier": "~2.4.3", @@ -99,6 +99,7 @@ "esbuild": "~0.14.18", "eslint-define-config": "~1.2.3", "eslint-gitignore": "~0.1.0", + "eslint-plugin-jsdoc": "~37.7.1", "eslint": "~8.8.0", "esno": "~0.14.0", "lint-staged": "~12.3.3", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 626c6514915..201b5b623ad 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1,7 +1,7 @@ lockfileVersion: 5.3 specifiers: - '@types/node': ~16.11.21 + '@types/node': ~16.11.22 '@types/prettier': ~2.4.3 '@types/validator': ~13.7.1 '@typescript-eslint/eslint-plugin': ~5.10.2 @@ -14,6 +14,7 @@ specifiers: eslint: ~8.8.0 eslint-define-config: ~1.2.3 eslint-gitignore: ~0.1.0 + eslint-plugin-jsdoc: ~37.7.1 esno: ~0.14.0 lint-staged: ~12.3.3 npm-run-all: ~4.1.5 @@ -30,7 +31,7 @@ specifiers: vitest: ~0.2.7 devDependencies: - '@types/node': 16.11.21 + '@types/node': 16.11.22 '@types/prettier': 2.4.3 '@types/validator': 13.7.1 '@typescript-eslint/eslint-plugin': 5.10.2_2595c2126aec4d4b6e944b931dabb4c2 @@ -43,6 +44,7 @@ devDependencies: eslint: 8.8.0 eslint-define-config: 1.2.3 eslint-gitignore: 0.1.0_eslint@8.8.0 + eslint-plugin-jsdoc: 37.7.1_eslint@8.8.0 esno: 0.14.0_typescript@4.5.5 lint-staged: 12.3.3 npm-run-all: 4.1.5 @@ -60,24 +62,24 @@ devDependencies: packages: - /@algolia/autocomplete-core/1.5.0: - resolution: {integrity: sha512-E7+VJwcvwMM8vPeaVn7fNUgix8WHV8A1WUeHDi2KHemCaaGc8lvUnP3QnvhMxiDhTe7OpMEv4o2TBUMyDgThaw==} + /@algolia/autocomplete-core/1.5.2: + resolution: {integrity: sha512-DY0bhyczFSS1b/CqJlTE/nQRtnTAHl6IemIkBy0nEWnhDzRDdtdx4p5Uuk3vwAFxwEEgi1WqKwgSSMx6DpNL4A==} dependencies: - '@algolia/autocomplete-shared': 1.5.0 + '@algolia/autocomplete-shared': 1.5.2 dev: true - /@algolia/autocomplete-preset-algolia/1.5.0_algoliasearch@4.12.1: - resolution: {integrity: sha512-iiFxKERGHkvkiupmrFJbvESpP/zv5jSgH714XRiP5LDvUHaYOo4GLAwZCFf2ef/L5tdtPBARvekn6k1Xf33gjA==} + /@algolia/autocomplete-preset-algolia/1.5.2_algoliasearch@4.12.1: + resolution: {integrity: sha512-3MRYnYQFJyovANzSX2CToS6/5cfVjbLLqFsZTKcvF3abhQzxbqwwaMBlJtt620uBUOeMzhdfasKhCc40+RHiZw==} peerDependencies: '@algolia/client-search': ^4.9.1 algoliasearch: ^4.9.1 dependencies: - '@algolia/autocomplete-shared': 1.5.0 + '@algolia/autocomplete-shared': 1.5.2 algoliasearch: 4.12.1 dev: true - /@algolia/autocomplete-shared/1.5.0: - resolution: {integrity: sha512-bRSkqHHHSwZYbFY3w9hgMyQRm86Wz27bRaGCbNldLfbk0zUjApmE4ajx+ZCVSLqxvcUEjMqZFJzDsder12eKsg==} + /@algolia/autocomplete-shared/1.5.2: + resolution: {integrity: sha512-ylQAYv5H0YKMfHgVWX0j0NmL8XBcAeeeVQUmppnnMtzDbDnca6CzhKj3Q8eF9cHCgcdTDdb5K+3aKyGWA0obug==} dev: true /@algolia/cache-browser-local-storage/4.12.1: @@ -191,8 +193,8 @@ packages: js-tokens: 4.0.0 dev: true - /@babel/parser/7.16.12: - resolution: {integrity: sha512-VfaV15po8RiZssrkPweyvbGVSe4x2y+aciFCgn0n0/SJMR22cwofRV1mtnJQYcSB1wUTaA/X1LnA3es66MCO5A==} + /@babel/parser/7.17.0: + resolution: {integrity: sha512-VKXSCQx5D8S04ej+Dqsr1CzYvvWgf20jIw2D+YhQCrIlr2UZGaDds23Y0xg75/skOxpLCRpUZvk/1EAVkGoDOw==} engines: {node: '>=6.0.0'} hasBin: true dev: true @@ -232,14 +234,14 @@ packages: lodash.once: 4.1.1 dev: true - /@docsearch/css/3.0.0-alpha.42: - resolution: {integrity: sha512-AGwI2AXUacYhVOHmYnsXoYDJKO6Ued2W+QO80GERbMLhC7GH5tfvtW5REs/s7jSdcU3vzFoxT8iPDBCh/PkrlQ==} + /@docsearch/css/3.0.0-alpha.50: + resolution: {integrity: sha512-QeWFCQOtS9D+Fi20liKsPXF2j/xWKh52e+P2Z1UATIdPMqmH6zoB2lcUz+cgv6PPVgWUtECeR6VSSUm71LT94w==} dev: true - /@docsearch/js/3.0.0-alpha.42: - resolution: {integrity: sha512-8rxxsvFKS5GzDX2MYMETeib4EOwAkoxVUHFP5R4tSENXojhuCEy3np+k3Q0c9WPT+MUmWLxKJab5jyl0jmaeBQ==} + /@docsearch/js/3.0.0-alpha.50: + resolution: {integrity: sha512-1ap9Wz5oR/Z8yybaCZhsptXU43es3H52eEQUZtmzb8dUWyCW+3iXaKVB/qeMJOQWtggZ/WvZV3YknVIbCMR2dQ==} dependencies: - '@docsearch/react': 3.0.0-alpha.42 + '@docsearch/react': 3.0.0-alpha.50 preact: 10.6.5 transitivePeerDependencies: - '@algolia/client-search' @@ -248,21 +250,30 @@ packages: - react-dom dev: true - /@docsearch/react/3.0.0-alpha.42: - resolution: {integrity: sha512-1aOslZJDxwUUcm2QRNmlEePUgL8P5fOAeFdOLDMctHQkV2iTja9/rKVbkP8FZbIUnZxuuCCn8ErLrjD/oXWOag==} + /@docsearch/react/3.0.0-alpha.50: + resolution: {integrity: sha512-oDGV1zZCRYv7MWsh6CyQVthYTRc3b4q+6kKwNYb1/g/Wf/4nJHutpxolFLHdEUDhrJ4Xi8wxwQG+lEwAVBTHPg==} peerDependencies: '@types/react': '>= 16.8.0 < 18.0.0' react: '>= 16.8.0 < 18.0.0' react-dom: '>= 16.8.0 < 18.0.0' dependencies: - '@algolia/autocomplete-core': 1.5.0 - '@algolia/autocomplete-preset-algolia': 1.5.0_algoliasearch@4.12.1 - '@docsearch/css': 3.0.0-alpha.42 + '@algolia/autocomplete-core': 1.5.2 + '@algolia/autocomplete-preset-algolia': 1.5.2_algoliasearch@4.12.1 + '@docsearch/css': 3.0.0-alpha.50 algoliasearch: 4.12.1 transitivePeerDependencies: - '@algolia/client-search' dev: true + /@es-joy/jsdoccomment/0.18.0: + resolution: {integrity: sha512-TjT8KJULV4I6ZiwIoKr6eMs+XpRejqwJ/VA+QPDeFGe9j6bZFKmMJ81EeFsGm6JNZhnzm37aoxVROmTh2PZoyA==} + engines: {node: ^12 || ^14 || ^16 || ^17} + dependencies: + comment-parser: 1.3.0 + esquery: 1.4.0 + jsdoc-type-pratt-parser: 2.2.2 + dev: true + /@eslint/eslintrc/1.0.5: resolution: {integrity: sha512-BLxsnmK3KyPunz5wmCCpqy0YelEoxxGmH73Is+Z74oOTMtExcjkr3dDR6quwrjh1YspA8DH9gnX1o069KiS9AQ==} engines: {node: ^12.22.0 || ^14.17.0 || >=16.0.0} @@ -270,7 +281,7 @@ packages: ajv: 6.12.6 debug: 4.3.3 espree: 9.3.0 - globals: 13.12.0 + globals: 13.12.1 ignore: 4.0.6 import-fresh: 3.3.0 js-yaml: 4.1.0 @@ -352,12 +363,12 @@ packages: resolution: {integrity: sha512-jhuKLIRrhvCPLqwPcx6INqmKeiA5EWrsCOPhrlFSrbrmU4ZMPjj5Ul/oLCMDO98XRUIwVm78xICz4EPCektzeQ==} dev: true - /@types/node/14.18.9: - resolution: {integrity: sha512-j11XSuRuAlft6vLDEX4RvhqC0KxNxx6QIyMXNb0vHHSNPXTPeiy3algESWmOOIzEtiEL0qiowPU3ewW9hHVa7Q==} + /@types/node/14.18.10: + resolution: {integrity: sha512-6iihJ/Pp5fsFJ/aEDGyvT4pHGmCpq7ToQ/yf4bl5SbVAvwpspYJ+v3jO7n8UyjhQVHTy+KNszOozDdv+O6sovQ==} dev: true - /@types/node/16.11.21: - resolution: {integrity: sha512-Pf8M1XD9i1ksZEcCP8vuSNwooJ/bZapNmIzpmsMaL+jMI+8mEYU3PKvs+xDNuQcJWF/x24WzY4qxLtB0zNow9A==} + /@types/node/16.11.22: + resolution: {integrity: sha512-DYNtJWauMQ9RNpesl4aVothr97/tIJM8HbyOXJ0AYT1Z2bEjLHyfjOBPAQQVMLf8h3kSShYfNk8Wnto8B2zHUA==} dev: true /@types/normalize-package-data/2.4.1: @@ -384,7 +395,7 @@ packages: resolution: {integrity: sha512-8uALY5LTvSuHgloDVUvWP3pIauILm+8/0pDMokuDYIoNsOkSwd5AiHBTSEJjKTDcZr5z8UpgOWZkxBF4iJftoA==} requiresBuild: true dependencies: - '@types/node': 16.11.21 + '@types/node': 16.11.22 dev: true optional: true @@ -534,7 +545,7 @@ packages: /@vue/compiler-core/3.2.29: resolution: {integrity: sha512-RePZ/J4Ub3sb7atQw6V6Rez+/5LCRHGFlSetT3N4VMrejqJnNPXKUt5AVm/9F5MJriy2w/VudEIvgscCfCWqxw==} dependencies: - '@babel/parser': 7.16.12 + '@babel/parser': 7.17.0 '@vue/shared': 3.2.29 estree-walker: 2.0.2 source-map: 0.6.1 @@ -550,7 +561,7 @@ packages: /@vue/compiler-sfc/3.2.29: resolution: {integrity: sha512-X9+0dwsag2u6hSOP/XsMYqFti/edvYvxamgBgCcbSYuXx1xLZN+dS/GvQKM4AgGS4djqo0jQvWfIXdfZ2ET68g==} dependencies: - '@babel/parser': 7.16.12 + '@babel/parser': 7.17.0 '@vue/compiler-core': 3.2.29 '@vue/compiler-dom': 3.2.29 '@vue/compiler-ssr': 3.2.29 @@ -558,7 +569,7 @@ packages: '@vue/shared': 3.2.29 estree-walker: 2.0.2 magic-string: 0.25.7 - postcss: 8.4.5 + postcss: 8.4.6 source-map: 0.6.1 dev: true @@ -572,7 +583,7 @@ packages: /@vue/reactivity-transform/3.2.29: resolution: {integrity: sha512-YF6HdOuhdOw6KyRm59+3rML8USb9o8mYM1q+SH0G41K3/q/G7uhPnHGKvspzceD7h9J3VR1waOQ93CUZj7J7OA==} dependencies: - '@babel/parser': 7.16.12 + '@babel/parser': 7.17.0 '@vue/compiler-core': 3.2.29 '@vue/shared': 3.2.29 estree-walker: 2.0.2 @@ -904,7 +915,7 @@ packages: check-error: 1.0.2 deep-eql: 3.0.1 get-func-name: 2.0.0 - loupe: 2.3.1 + loupe: 2.3.3 pathval: 1.1.1 type-detect: 4.0.8 dev: true @@ -1033,6 +1044,11 @@ packages: engines: {node: '>= 12'} dev: true + /comment-parser/1.3.0: + resolution: {integrity: sha512-hRpmWIKgzd81vn0ydoWoyPoALEOnF4wt8yKD35Ib1D6XC2siLiYaiqfGkYrunuKdsXGwpBpHU3+9r+RVw2NZfA==} + engines: {node: '>= 12.0.0'} + dev: true + /common-tags/1.8.2: resolution: {integrity: sha512-gk/Z852D2Wtb//0I+kRFNKKE9dIIVirjoqPoA1wJU+XePVXZfGeBpk45+A1rKO4Q43prqWBNY/MiIeRLbPWUaA==} engines: {node: '>=4.0.0'} @@ -1253,7 +1269,7 @@ packages: dependencies: '@cypress/request': 2.88.10 '@cypress/xvfb': 1.2.4 - '@types/node': 14.18.9 + '@types/node': 14.18.10 '@types/sinonjs__fake-timers': 8.1.1 '@types/sizzle': 2.3.3 arch: 2.2.0 @@ -1888,6 +1904,25 @@ packages: - supports-color dev: true + /eslint-plugin-jsdoc/37.7.1_eslint@8.8.0: + resolution: {integrity: sha512-ySxDTedl6qKXT/VeTwcZlhsRtvNQZGPklyVnaL5+ge20vowzFA9CKvrY0NXRqvdIz6JBVMFpxX9DSmS3OyAUOQ==} + engines: {node: ^12 || ^14 || ^16 || ^17} + peerDependencies: + eslint: ^7.0.0 || ^8.0.0 + dependencies: + '@es-joy/jsdoccomment': 0.18.0 + comment-parser: 1.3.0 + debug: 4.3.3 + escape-string-regexp: 4.0.0 + eslint: 8.8.0 + esquery: 1.4.0 + regextras: 0.8.0 + semver: 7.3.5 + spdx-expression-parse: 3.0.1 + transitivePeerDependencies: + - supports-color + dev: true + /eslint-scope/5.1.1: resolution: {integrity: sha512-2NxwbF/hZ0KpepYN0cNbo+FN6XoK7GaHlQhgx/hIZl6Va0bF45RQOOwhLIy8lQDbuCiadSLCBnH2CFYquit5bw==} engines: {node: '>=8.0.0'} @@ -1947,7 +1982,7 @@ packages: file-entry-cache: 6.0.1 functional-red-black-tree: 1.0.1 glob-parent: 6.0.2 - globals: 13.12.0 + globals: 13.12.1 ignore: 5.2.0 import-fresh: 3.3.0 imurmurhash: 0.1.4 @@ -2038,7 +2073,7 @@ packages: merge-stream: 2.0.0 npm-run-path: 4.0.1 onetime: 5.1.2 - signal-exit: 3.0.6 + signal-exit: 3.0.7 strip-final-newline: 2.0.0 dev: true @@ -2053,7 +2088,7 @@ packages: merge-stream: 2.0.0 npm-run-path: 4.0.1 onetime: 5.1.2 - signal-exit: 3.0.6 + signal-exit: 3.0.7 strip-final-newline: 2.0.0 dev: true @@ -2183,7 +2218,7 @@ packages: engines: {node: '>=8.0.0'} dependencies: cross-spawn: 7.0.3 - signal-exit: 3.0.6 + signal-exit: 3.0.7 dev: true /forever-agent/0.6.1: @@ -2356,8 +2391,8 @@ packages: ini: 2.0.0 dev: true - /globals/13.12.0: - resolution: {integrity: sha512-uS8X6lSKN2JumVoXrbUz+uG4BYG+eiawqm3qFcT7ammfbUHeCBoJMlHcec/S3krSk73/AE/f0szYFmgAA3kYZg==} + /globals/13.12.1: + resolution: {integrity: sha512-317dFlgY2pdJZ9rspXDks7073GpDmXdfbM3vYYp0HAMKGDh1FfWPleI2ljVNLQX5M5lXcAslTcPTrOrMEFOjyw==} engines: {node: '>=8'} dependencies: type-fest: 0.20.2 @@ -2738,6 +2773,11 @@ packages: resolution: {integrity: sha1-peZUwuWi3rXyAdls77yoDA7y9RM=} dev: true + /jsdoc-type-pratt-parser/2.2.2: + resolution: {integrity: sha512-zRokSWcPLSWkoNzsWn9pq7YYSwDhKyEe+cJYT2qaPqLOOJb5sFSi46BPj81vP+e8chvCNdQL9RG86Bi9EI6MDw==} + engines: {node: '>=12.0.0'} + dev: true + /json-parse-better-errors/1.0.2: resolution: {integrity: sha512-mrqyZKfX5EhL7hvqcV6WG1yYjnjeuYDzDhhcAAUrq8Po85NBQBJP+ZDUT75qZQ98IkUoBqdkExkukOU7Ts2wrw==} dev: true @@ -2827,7 +2867,7 @@ packages: debug: 4.3.3_supports-color@9.2.1 execa: 5.1.1 lilconfig: 2.0.4 - listr2: 4.0.1 + listr2: 4.0.2 micromatch: 4.0.4 normalize-path: 3.0.0 object-inspect: 1.12.0 @@ -2858,8 +2898,8 @@ packages: wrap-ansi: 7.0.0 dev: true - /listr2/4.0.1: - resolution: {integrity: sha512-D65Nl+zyYHL2jQBGmxtH/pU8koPZo5C8iCNE8EoB04RwPgQG1wuaKwVbeZv9LJpiH4Nxs0FCp+nNcG8OqpniiA==} + /listr2/4.0.2: + resolution: {integrity: sha512-YcgwfCWpvPbj9FLUGqvdFvd3hrFWKpOeuXznRgfWEJ7RNr8b/IKKIKZABHx3aU+4CWN/iSAFFSReziQG6vTeIA==} engines: {node: '>=12'} peerDependencies: enquirer: '>= 2.3.0 < 3' @@ -2948,8 +2988,8 @@ packages: wrap-ansi: 6.2.0 dev: true - /loupe/2.3.1: - resolution: {integrity: sha512-EN1D3jyVmaX4tnajVlfbREU4axL647hLec1h/PXAb8CPDMJiYitcWF2UeLVNttRqaIqQs4x+mRvXf+d+TlDrCA==} + /loupe/2.3.3: + resolution: {integrity: sha512-krIV4Cf1BIGIx2t1e6tucThhrBemUnIUjMtD2vN4mrMxnxpBvrcosBSpooqunBqP/hOEEV1w/Cr1YskGtqw5Jg==} dependencies: get-func-name: 2.0.0 dev: true @@ -3367,8 +3407,8 @@ packages: engines: {node: '>=4'} dev: true - /postcss/8.4.5: - resolution: {integrity: sha512-jBDboWM8qpaqwkMwItqTQTiFikhs/67OYVvblFFTM7MrZjt6yMKd6r2kgXizEbTTljacm4NldIlZnhbjr84QYg==} + /postcss/8.4.6: + resolution: {integrity: sha512-OovjwIzs9Te46vlEx7+uXB0PLijpwjXGKXjVGGPIGubGpq7uh5Xgf6D6FiJ/SzJMBosHDp6a2hiXOS97iBXcaA==} engines: {node: ^10 || ^12 || >=14} dependencies: nanoid: 3.2.0 @@ -3514,6 +3554,11 @@ packages: engines: {node: '>=8'} dev: true + /regextras/0.8.0: + resolution: {integrity: sha512-k519uI04Z3SaY0fLX843MRXnDeG2+vHOFsyhiPZvNLe7r8rD2YNRjq4BQLZZ0oAr2NrtvZlICsXysGNFPGa3CQ==} + engines: {node: '>=0.1.14'} + dev: true + /request-progress/3.0.0: resolution: {integrity: sha1-TKdUCBx/7GP1BeT6qCWqBs1mnb4=} dependencies: @@ -3544,7 +3589,7 @@ packages: engines: {node: '>=8'} dependencies: onetime: 5.1.2 - signal-exit: 3.0.6 + signal-exit: 3.0.7 dev: true /reusify/1.0.4: @@ -3563,8 +3608,8 @@ packages: glob: 7.2.0 dev: true - /rollup/2.66.1: - resolution: {integrity: sha512-crSgLhSkLMnKr4s9iZ/1qJCplgAgrRY+igWv8KhG/AjKOJ0YX/WpmANyn8oxrw+zenF3BXWDLa7Xl/QZISH+7w==} + /rollup/2.67.0: + resolution: {integrity: sha512-W83AaERwvDiHwHEF/dfAfS3z1Be5wf7n+pO3ZAO5IQadCT2lBTr7WQ2MwZZe+nodbD+n3HtC4OCOAdsOPPcKZQ==} engines: {node: '>=10.0.0'} hasBin: true optionalDependencies: @@ -3657,8 +3702,8 @@ packages: object-inspect: 1.12.0 dev: true - /signal-exit/3.0.6: - resolution: {integrity: sha512-sDl4qMFpijcGw22U5w63KmD3cZJfBuFlVNbVMKje2keoKML7X2UzWbc4XrmEbDwg0NXJc3yv4/ox7b+JWb57kQ==} + /signal-exit/3.0.7: + resolution: {integrity: sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==} dev: true /simple-git-hooks/2.7.0: @@ -4188,9 +4233,9 @@ packages: optional: true dependencies: esbuild: 0.13.15 - postcss: 8.4.5 + postcss: 8.4.6 resolve: 1.22.0 - rollup: 2.66.1 + rollup: 2.67.0 optionalDependencies: fsevents: 2.3.2 dev: true @@ -4200,8 +4245,8 @@ packages: engines: {node: '>=12.0.0'} hasBin: true dependencies: - '@docsearch/css': 3.0.0-alpha.42 - '@docsearch/js': 3.0.0-alpha.42 + '@docsearch/css': 3.0.0-alpha.50 + '@docsearch/js': 3.0.0-alpha.50 '@vitejs/plugin-vue': 2.1.0_vite@2.7.13+vue@3.2.29 prismjs: 1.26.0 vite: 2.7.13