Vue3 + TypeScript 项目中规范注释和生成文档

在 Vue3 + TypeScript 项目中规范注释和生成文档，可以通过以下方案实现：

一、注释规范 (JSDoc 标准)

1. 组件级注释

vue

复制

下载

<script lang="ts">
/**
 * 用户卡片组件
 * @displayName UserCard
 * @version 1.0.0
 * @example
 * <UserCard :user="userData" />
 */
import { defineComponent } from 'vue'
export default defineComponent({...})
</script>

2. Props 注释

ts

复制

下载

props: {
  /** 用户信息对象 */
  user: {
    type: Object as PropType<User>,
    required: true,
    validator: (u: User) => u.id > 0
  },
  
  /** 
   * 是否显示邮箱
   * @since v1.2.0 
   */
  showEmail: {
    type: Boolean,
    default: false
  }
}

3. 方法/函数注释

ts

复制

下载

/**
 * 提交用户数据
 * @param {User} formData - 用户表单数据
 * @returns {Promise<ApiResponse>} API响应结果
 * @throws {Error} 当验证失败时抛出错误
 */
async function submitUser(formData: User): Promise<ApiResponse> {
  // ...
}

4. TypeScript 类型注释

ts

复制

下载

/** 用户基础信息 */
interface User {
  /** 用户ID */
  id: number;
  
  /**
   * 用户名
   * @pattern ^[a-zA-Z0-9_]{3,20}$
   */
  username: string;
}

二、文档生成工具

1. Vue 组件文档 (推荐组合)

bash

复制

下载

# 安装依赖
npm install -D vue-docgen-api vue-docgen-cli vitepress

配置步骤：

1. 创建 docs 目录

2. 添加 vitepress 配置文件 (docs/.vitepress/config.ts)

3. 生成组件文档：

bash

复制

下载

npx vue-docgen -c ./src/components -d ./docs/components

2. TypeScript API 文档 (TypeDoc)

bash

复制

下载

npm install -D typedoc

配置命令 (package.json)：

json

复制

下载

"scripts": {
  "docs:api": "typedoc --out docs/api src/core --plugin typedoc-plugin-markdown"
}

3. 完整文档站点示例 (Vitepress)

text

复制

下载

docs/
├─ .vitepress/
│  └─ config.ts
├─ components/
│  ├─ Button.md   // 自动生成
│  └─ UserCard.md // 自动生成
└─ index.md

三、高级配置方案

1. Vitepress 集成配置 (config.ts)

ts

复制

下载

// docs/.vitepress/config.ts
export default {
  themeConfig: {
    sidebar: [
      {
        text: '组件文档',
        items: [
          { text: 'UserCard', link: '/components/UserCard' },
          { text: 'API 参考', link: '/api/' }
        ]
      }
    ]
  }
}

2. TypeDoc 配置 (typedoc.json)

json

复制

下载

{
  "entryPoints": ["src/core"],
  "out": "docs/api",
  "exclude": ["**/__tests__/**", "**/*.vue"],
  "plugin": ["typedoc-plugin-markdown"],
  "hideGenerator": true
}

3. 自定义文档模板 (覆盖默认生成)

在组件同级目录添加 UserCard.docs.md：

markdown

复制

下载

---
displayName: 用户卡片
---

# UserCard

<component-info src="./UserCard.vue" />

## 高级用法
```vue
<template>
  <UserCard :user="admin" theme="dark" />
</template>

text

复制

下载

---

### 四、注释规范检查
#### ESLint 配置 (`.eslintrc.js`)
```js
module.exports = {
  plugins: ['jsdoc'],
  rules: {
    'jsdoc/require-description': 'warn',
    'jsdoc/require-param': 'warn',
    'jsdoc/require-returns': 'warn',
    'jsdoc/require-throws': 'warn'
  }
}

安装依赖：

bash

复制

下载

npm install -D eslint-plugin-jsdoc

五、最佳实践建议

1. 组件文档必须包含：

   • @displayName (显示名称)

   • @version (版本标记)

   • @example (使用示例)

2. TypeScript 类型：

   • 使用 /** 描述 */ 代替 // 注释

   • 为复杂类型添加 @example 示例

3. 自动化流程：

   json

   复制

   下载

   "scripts": {
     "docs": "npm run docs:components && npm run docs:api",
     "docs:components": "vue-docgen -c ./src/components",
     "docs:api": "typedoc --out docs/api src/core"
   }

4. 文档预览：

   bash

   复制

   下载

   npx vitepress dev docs  # 启动文档本地服务器

六、工具对比

推荐组合：VueDocGen + TypeDoc + Vitepress 三件套，覆盖所有文档需求

通过规范化的 JSDoc 注释配合自动化文档工具，可在 Vue3+TS 项目中：

1. 生成专业级组件文档

2. 保持代码与文档实时同步

3. 提升团队协作效率

4. 自动生成类型定义文档

5. 提供可交互的示例演示