🔧 tsdoc格式化配置

2026-03-15 03:53:16 +08:00 · 2025-12-23 00:42:29 +08:00
parent 88cd657525
commit e780db9936
5 changed files with 173 additions and 9 deletions
--- 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: {
--- 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 = {
--- 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",
--- 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: {}
--- a/tsdoc.json
+++ 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"
+    }
+  ]
+}