From e780db9936eaab9e0a83b61134173e81e87d831b Mon Sep 17 00:00:00 2001 From: BTMuli Date: Tue, 23 Dec 2025 00:42:29 +0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=94=A7=20tsdoc=E6=A0=BC=E5=BC=8F=E5=8C=96?= =?UTF-8?q?=E9=85=8D=E7=BD=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- eslint/jsonEslint.js | 7 +-- eslint/vueEslint.js | 13 ++-- package.json | 2 + pnpm-lock.yaml | 138 +++++++++++++++++++++++++++++++++++++++++++ tsdoc.json | 22 +++++++ 5 files changed, 173 insertions(+), 9 deletions(-) create mode 100644 tsdoc.json diff --git a/eslint/jsonEslint.js b/eslint/jsonEslint.js index 6882cd08..f22fcb5e 100644 --- a/eslint/jsonEslint.js +++ b/eslint/jsonEslint.js @@ -1,7 +1,6 @@ /** - * @file eslint/jsonEslint.js - * @description JSON相关的ESLint配置 - * @since Beta v0.7.7 + * JSON 文件的 ESLint 配置 + * @since Beta v0.9.1 */ import pluginJsonc from "eslint-plugin-jsonc"; @@ -63,7 +62,7 @@ const tscJsonConfig = { }; const jsoncConfig = { - files: ["source/data/out/**/*.json", ".vscode/**/*.json"], + files: ["source/data/out/**/*.json", ".vscode/**/*.json", "./tsdoc.json"], plugins: { jsonc: pluginJsonc }, languageOptions: { parser: parserJsonc }, rules: { diff --git a/eslint/vueEslint.js b/eslint/vueEslint.js index 7cba8b93..8fcdff70 100644 --- a/eslint/vueEslint.js +++ b/eslint/vueEslint.js @@ -1,11 +1,11 @@ /** - * @file eslint/vueEslint.js - * @description Vue相关的ESLint配置 - * @since Beta v0.8.0 + * Vue&Typescirpt 文件的 Eslint 配置 + * @since Beta v0.9.1 */ import pluginImport from "eslint-plugin-import"; import pluginPrettier from "eslint-plugin-prettier"; import pluginVue from "eslint-plugin-vue"; +import pluginTsDoc from "eslint-plugin-tsdoc"; import globals from "globals"; import eslintTs from "typescript-eslint"; import parserVue from "vue-eslint-parser"; @@ -30,12 +30,15 @@ const tsConfigRules = { const tsConfig = { files: ["*.ts", "*.d.ts", "src/**/*.ts", "src/**/*.d.ts"], - plugins: { typescript: eslintTs, import: pluginImport, prettier: pluginPrettier }, + plugins: { typescript: eslintTs, import: pluginImport, prettier: pluginPrettier, tsdoc: pluginTsDoc }, languageOptions: { parser: eslintTs.parser, parserOptions: { project: "tsconfig.json", tsconfigRootDir: appRootPath.path }, }, - rules: tsConfigRules, + rules: { + ...tsConfigRules, + "tsdoc/syntax": "warn", + }, }; const vueConfig = { diff --git a/package.json b/package.json index 2af57e3c..30aed952 100644 --- a/package.json +++ b/package.json @@ -106,6 +106,7 @@ "@btmuli/stylelint-plugin-color": "^0.1.0", "@eslint/eslintrc": "^3.3.3", "@eslint/js": "^9.39.2", + "@microsoft/tsdoc": "^0.16.0", "@tauri-apps/cli": "2.9.6", "@types/fs-extra": "^11.0.4", "@types/js-md5": "^0.8.0", @@ -119,6 +120,7 @@ "eslint-plugin-import": "^2.32.0", "eslint-plugin-jsonc": "^2.21.0", "eslint-plugin-prettier": "^5.5.4", + "eslint-plugin-tsdoc": "^0.5.0", "eslint-plugin-vue": "^10.6.2", "eslint-plugin-yml": "^1.19.1", "fs-extra": "^11.3.3", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 8d90ab14..fc6aca67 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -111,6 +111,9 @@ importers: '@eslint/js': specifier: ^9.39.2 version: 9.39.2 + '@microsoft/tsdoc': + specifier: ^0.16.0 + version: 0.16.0 '@tauri-apps/cli': specifier: 2.9.6 version: 2.9.6 @@ -150,6 +153,9 @@ importers: eslint-plugin-prettier: specifier: ^5.5.4 version: 5.5.4(@types/eslint@9.6.1)(eslint-config-prettier@9.1.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))(prettier@3.7.4) + eslint-plugin-tsdoc: + specifier: ^0.5.0 + version: 0.5.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3) eslint-plugin-vue: specifier: ^10.6.2 version: 10.6.2(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1))(vue-eslint-parser@10.2.0(eslint@9.39.2(jiti@2.6.1))) @@ -934,6 +940,12 @@ packages: '@mdi/font@7.4.47': resolution: {integrity: sha512-43MtGpd585SNzHZPcYowu/84Vz2a2g31TvPMTm9uTiCSWzaheQySUcSyUH/46fPnuPQWof2yd0pGBtzee/IQWw==} + '@microsoft/tsdoc-config@0.18.0': + resolution: {integrity: sha512-8N/vClYyfOH+l4fLkkr9+myAoR6M7akc8ntBJ4DJdWH2b09uVfr71+LTMpNyG19fNqWDg8KEDZhx5wxuqHyGjw==} + + '@microsoft/tsdoc@0.16.0': + resolution: {integrity: sha512-xgAyonlVVS+q7Vc7qLW0UrJU7rSFcETRWsqdXZtjzRU8dF+6CkozTK4V4y1LwOX7j8r/vHphjDeMeGI4tNGeGA==} + '@napi-rs/wasm-runtime@1.1.0': resolution: {integrity: sha512-Fq6DJW+Bb5jaWE69/qOE0D1TUN9+6uWhCeZpdnSBk14pjLcCWR7Q8n49PTSPHazM37JqrsdpEthXy2xn6jWWiA==} @@ -1319,16 +1331,32 @@ packages: eslint: ^8.57.0 || ^9.0.0 typescript: '>=4.8.4 <6.0.0' + '@typescript-eslint/project-service@8.46.4': + resolution: {integrity: sha512-nPiRSKuvtTN+no/2N1kt2tUh/HoFzeEgOm9fQ6XQk4/ApGqjx0zFIIaLJ6wooR1HIoozvj2j6vTi/1fgAz7UYQ==} + engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + peerDependencies: + typescript: '>=4.8.4 <6.0.0' + '@typescript-eslint/project-service@8.50.0': resolution: {integrity: sha512-Cg/nQcL1BcoTijEWyx4mkVC56r8dj44bFDvBdygifuS20f3OZCHmFbjF34DPSi07kwlFvqfv/xOLnJ5DquxSGQ==} engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} peerDependencies: typescript: '>=4.8.4 <6.0.0' + '@typescript-eslint/scope-manager@8.46.4': + resolution: {integrity: sha512-tMDbLGXb1wC+McN1M6QeDx7P7c0UWO5z9CXqp7J8E+xGcJuUuevWKxuG8j41FoweS3+L41SkyKKkia16jpX7CA==} + engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + '@typescript-eslint/scope-manager@8.50.0': resolution: {integrity: sha512-xCwfuCZjhIqy7+HKxBLrDVT5q/iq7XBVBXLn57RTIIpelLtEIZHXAF/Upa3+gaCpeV1NNS5Z9A+ID6jn50VD4A==} engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + '@typescript-eslint/tsconfig-utils@8.46.4': + resolution: {integrity: sha512-+/XqaZPIAk6Cjg7NWgSGe27X4zMGqrFqZ8atJsX3CWxH/jACqWnrWI68h7nHQld0y+k9eTTjb9r+KU4twLoo9A==} + engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + peerDependencies: + typescript: '>=4.8.4 <6.0.0' + '@typescript-eslint/tsconfig-utils@8.50.0': resolution: {integrity: sha512-vxd3G/ybKTSlm31MOA96gqvrRGv9RJ7LGtZCn2Vrc5htA0zCDvcMqUkifcjrWNNKXHUU3WCkYOzzVSFBd0wa2w==} engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} @@ -1342,16 +1370,33 @@ packages: eslint: ^8.57.0 || ^9.0.0 typescript: '>=4.8.4 <6.0.0' + '@typescript-eslint/types@8.46.4': + resolution: {integrity: sha512-USjyxm3gQEePdUwJBFjjGNG18xY9A2grDVGuk7/9AkjIF1L+ZrVnwR5VAU5JXtUnBL/Nwt3H31KlRDaksnM7/w==} + engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + '@typescript-eslint/types@8.50.0': resolution: {integrity: sha512-iX1mgmGrXdANhhITbpp2QQM2fGehBse9LbTf0sidWK6yg/NE+uhV5dfU1g6EYPlcReYmkE9QLPq/2irKAmtS9w==} engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + '@typescript-eslint/typescript-estree@8.46.4': + resolution: {integrity: sha512-7oV2qEOr1d4NWNmpXLR35LvCfOkTNymY9oyW+lUHkmCno7aOmIf/hMaydnJBUTBMRCOGZh8YjkFOc8dadEoNGA==} + engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + peerDependencies: + typescript: '>=4.8.4 <6.0.0' + '@typescript-eslint/typescript-estree@8.50.0': resolution: {integrity: sha512-W7SVAGBR/IX7zm1t70Yujpbk+zdPq/u4soeFSknWFdXIFuWsBGBOUu/Tn/I6KHSKvSh91OiMuaSnYp3mtPt5IQ==} engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} peerDependencies: typescript: '>=4.8.4 <6.0.0' + '@typescript-eslint/utils@8.46.4': + resolution: {integrity: sha512-AbSv11fklGXV6T28dp2Me04Uw90R2iJ30g2bgLz529Koehrmkbs1r7paFqr1vPCZi7hHwYxYtxfyQMRC8QaVSg==} + engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + peerDependencies: + eslint: ^8.57.0 || ^9.0.0 + typescript: '>=4.8.4 <6.0.0' + '@typescript-eslint/utils@8.50.0': resolution: {integrity: sha512-87KgUXET09CRjGCi2Ejxy3PULXna63/bMYv72tCAlDJC3Yqwln0HiFJ3VJMst2+mEtNtZu5oFvX4qJGjKsnAgg==} engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} @@ -1359,6 +1404,10 @@ packages: eslint: ^8.57.0 || ^9.0.0 typescript: '>=4.8.4 <6.0.0' + '@typescript-eslint/visitor-keys@8.46.4': + resolution: {integrity: sha512-/++5CYLQqsO9HFGLI7APrxBJYo+5OCMpViuhV8q5/Qa3o5mMrF//eQHks+PXcsAVaLdn817fMuS7zqoXNNZGaw==} + engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + '@typescript-eslint/visitor-keys@8.50.0': resolution: {integrity: sha512-Xzmnb58+Db78gT/CCj/PVCvK+zxbnsw6F+O1oheYszJbBSdEjVhQi3C/Xttzxgi/GLmpvOggRs1RFpiJ8+c34Q==} engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} @@ -1508,6 +1557,9 @@ packages: ajv@6.12.6: resolution: {integrity: sha512-j3fVLgvTo527anyYyJOGTYJbG+vnnQYvE0m5mmkc1TK+nxAppkCLMIL0aZ4dblVCNoGShhm+kzE4ZUykBoMg4g==} + ajv@8.12.0: + resolution: {integrity: sha512-sRu1kpcO9yLtYxBKvqfTeh9KzZEwO3STyX1HT+4CaDzC6HpTGYhIhPIzj9XuKU7KYDwnaeh5hcOwjy1QuJzBPA==} + ajv@8.17.1: resolution: {integrity: sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==} @@ -2057,6 +2109,9 @@ packages: eslint-config-prettier: optional: true + eslint-plugin-tsdoc@0.5.0: + resolution: {integrity: sha512-ush8ehCwub2rgE16OIgQPFyj/o0k3T8kL++9IrAI4knsmupNo8gvfO2ERgDHWWgTC5MglbwLVRswU93HyXqNpw==} + eslint-plugin-vue@10.6.2: resolution: {integrity: sha512-nA5yUs/B1KmKzvC42fyD0+l9Yd+LtEpVhWRbXuDj0e+ZURcTtyRbMDWUeJmTAh2wC6jC83raS63anNM2YT3NPw==} engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} @@ -2523,6 +2578,9 @@ packages: resolution: {integrity: sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ==} hasBin: true + jju@1.4.0: + resolution: {integrity: sha512-8wb9Yw966OSxApiCt0K3yNJL8pnNeIv+OEq2YMidz4FKP6nonSRoOXc80iXY4JaN2FC11B9qsNmDsm+ZOfMROA==} + js-md5@0.8.3: resolution: {integrity: sha512-qR0HB5uP6wCuRMrWPTrkMaev7MJZwJuuw4fnwAzRgP4J4/F8RwtodOKpGp4XpqsLBFzzgqIO42efFAyz2Et6KQ==} @@ -4727,6 +4785,15 @@ snapshots: '@mdi/font@7.4.47': {} + '@microsoft/tsdoc-config@0.18.0': + dependencies: + '@microsoft/tsdoc': 0.16.0 + ajv: 8.12.0 + jju: 1.4.0 + resolve: 1.22.11 + + '@microsoft/tsdoc@0.16.0': {} + '@napi-rs/wasm-runtime@1.1.0': dependencies: '@emnapi/core': 1.7.1 @@ -5061,6 +5128,15 @@ snapshots: transitivePeerDependencies: - supports-color + '@typescript-eslint/project-service@8.46.4(typescript@5.9.3)': + dependencies: + '@typescript-eslint/tsconfig-utils': 8.50.0(typescript@5.9.3) + '@typescript-eslint/types': 8.50.0 + debug: 4.4.3 + typescript: 5.9.3 + transitivePeerDependencies: + - supports-color + '@typescript-eslint/project-service@8.50.0(typescript@5.9.3)': dependencies: '@typescript-eslint/tsconfig-utils': 8.50.0(typescript@5.9.3) @@ -5070,11 +5146,20 @@ snapshots: transitivePeerDependencies: - supports-color + '@typescript-eslint/scope-manager@8.46.4': + dependencies: + '@typescript-eslint/types': 8.46.4 + '@typescript-eslint/visitor-keys': 8.46.4 + '@typescript-eslint/scope-manager@8.50.0': dependencies: '@typescript-eslint/types': 8.50.0 '@typescript-eslint/visitor-keys': 8.50.0 + '@typescript-eslint/tsconfig-utils@8.46.4(typescript@5.9.3)': + dependencies: + typescript: 5.9.3 + '@typescript-eslint/tsconfig-utils@8.50.0(typescript@5.9.3)': dependencies: typescript: 5.9.3 @@ -5091,8 +5176,26 @@ snapshots: transitivePeerDependencies: - supports-color + '@typescript-eslint/types@8.46.4': {} + '@typescript-eslint/types@8.50.0': {} + '@typescript-eslint/typescript-estree@8.46.4(typescript@5.9.3)': + dependencies: + '@typescript-eslint/project-service': 8.46.4(typescript@5.9.3) + '@typescript-eslint/tsconfig-utils': 8.46.4(typescript@5.9.3) + '@typescript-eslint/types': 8.46.4 + '@typescript-eslint/visitor-keys': 8.46.4 + debug: 4.4.3 + fast-glob: 3.3.3 + is-glob: 4.0.3 + minimatch: 9.0.5 + semver: 7.7.3 + ts-api-utils: 2.1.0(typescript@5.9.3) + typescript: 5.9.3 + transitivePeerDependencies: + - supports-color + '@typescript-eslint/typescript-estree@8.50.0(typescript@5.9.3)': dependencies: '@typescript-eslint/project-service': 8.50.0(typescript@5.9.3) @@ -5108,6 +5211,17 @@ snapshots: transitivePeerDependencies: - supports-color + '@typescript-eslint/utils@8.46.4(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)': + dependencies: + '@eslint-community/eslint-utils': 4.9.0(eslint@9.39.2(jiti@2.6.1)) + '@typescript-eslint/scope-manager': 8.46.4 + '@typescript-eslint/types': 8.46.4 + '@typescript-eslint/typescript-estree': 8.46.4(typescript@5.9.3) + eslint: 9.39.2(jiti@2.6.1) + typescript: 5.9.3 + transitivePeerDependencies: + - supports-color + '@typescript-eslint/utils@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)': dependencies: '@eslint-community/eslint-utils': 4.9.0(eslint@9.39.2(jiti@2.6.1)) @@ -5119,6 +5233,11 @@ snapshots: transitivePeerDependencies: - supports-color + '@typescript-eslint/visitor-keys@8.46.4': + dependencies: + '@typescript-eslint/types': 8.46.4 + eslint-visitor-keys: 4.2.1 + '@typescript-eslint/visitor-keys@8.50.0': dependencies: '@typescript-eslint/types': 8.50.0 @@ -5331,6 +5450,13 @@ snapshots: json-schema-traverse: 0.4.1 uri-js: 4.4.1 + ajv@8.12.0: + dependencies: + fast-deep-equal: 3.1.3 + json-schema-traverse: 1.0.0 + require-from-string: 2.0.2 + uri-js: 4.4.1 + ajv@8.17.1: dependencies: fast-deep-equal: 3.1.3 @@ -5976,6 +6102,16 @@ snapshots: '@types/eslint': 9.6.1 eslint-config-prettier: 9.1.0(eslint@9.39.2(jiti@2.6.1)) + eslint-plugin-tsdoc@0.5.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3): + dependencies: + '@microsoft/tsdoc': 0.16.0 + '@microsoft/tsdoc-config': 0.18.0 + '@typescript-eslint/utils': 8.46.4(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3) + transitivePeerDependencies: + - eslint + - supports-color + - typescript + eslint-plugin-vue@10.6.2(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1))(vue-eslint-parser@10.2.0(eslint@9.39.2(jiti@2.6.1))): dependencies: '@eslint-community/eslint-utils': 4.9.0(eslint@9.39.2(jiti@2.6.1)) @@ -6467,6 +6603,8 @@ snapshots: jiti@2.6.1: optional: true + jju@1.4.0: {} + js-md5@0.8.3: {} js-tokens@4.0.0: {} diff --git a/tsdoc.json b/tsdoc.json new file mode 100644 index 00000000..20778bcc --- /dev/null +++ b/tsdoc.json @@ -0,0 +1,22 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", + "supportForTags": { + "@since": true, + "@link": true, + "@remarks": true, + "@param": true, + "@returns": true, + "@TODO": true + }, + "tagDefinitions": [ + { + "tagName": "@since", + "syntaxKind": "block", + "allowMultiple": false + }, + { + "tagName": "@TODO", + "syntaxKind": "block" + } + ] +}