如何为 Vue 组件库编写详细的 `JSDoc` 或 `TypeScript` 文档，并自动生成 API 文档？

Vue 组件库文档生成：从 JSDoc/TypeScript 到 API 文档的奇妙旅程

各位同学们，大家好！今天咱们来聊聊一个稍微有点枯燥，但绝对非常有用的东西：Vue 组件库的文档生成。别怕，咱们尽量讲得有趣一点，争取让大家听完之后，不仅知道怎么做，还能明白为什么要这么做。

想象一下，你辛辛苦苦写了一堆漂亮的 Vue 组件，功能强大，性能卓越。但是，如果没有一份清晰易懂的文档，别人怎么知道怎么用呢？难道要让大家直接啃你的代码吗？（除非你的代码写得像诗一样，但估计也没几个人能看懂诗里的变量名 a, b, c 吧…）

所以，文档的重要性不言而喻。而一份好的文档，不仅能帮助用户快速上手，还能提升你的组件库的专业度和可维护性。

那么，问题来了：如何编写一份高质量的 Vue 组件文档，并自动生成 API 文档呢？ 答案就是：JSDoc 或 TypeScript + 文档生成工具。

第一部分：选择你的武器：JSDoc vs TypeScript

在开始之前，我们需要先选择一下你的武器。 是使用 JSDoc 还是 TypeScript 呢？

• JSDoc: 简单易学，适用于现有的 JavaScript 项目，可以在现有的 JavaScript 代码上添加注释，生成文档。
• TypeScript: 静态类型检查，更强大的代码提示和重构能力，更易于维护大型项目。

如果你已经在使用 JavaScript，并且不想迁移到 TypeScript，那么 JSDoc 是一个不错的选择。如果你的项目是新的，或者你希望拥有更好的类型安全性和开发体验，那么 TypeScript 绝对是首选。

简单来说，JSDoc 相当于给你的代码打补丁，让它看起来像有类型一样；而 TypeScript 则是直接用类型武装你的代码，让它从一开始就更加健壮。

第二部分：JSDoc 的使用方法

JSDoc 是一种用于注释 JavaScript 代码的标记语言。通过在代码中添加 JSDoc 注释，你可以描述变量、函数、类、组件等，并使用文档生成工具自动生成 API 文档。

JSDoc 的基本语法：

JSDoc 注释以 /** 开头，以 */ 结尾。注释内部可以使用各种 JSDoc 标签来描述代码。

/**
 * 这是一个简单的函数示例。
 *
 * @param {number} a  第一个数字。
 * @param {number} b  第二个数字。
 * @returns {number}  两个数字的和。
 */
function add(a, b) {
  return a + b;
}

常用的 JSDoc 标签：

标签	描述
@param	描述函数的参数。
@returns	描述函数的返回值。
@typedef	定义一个类型。
@property	描述一个对象的属性。
@class	描述一个类。
@constructor	描述一个构造函数。
@method	描述一个方法。
@event	描述一个事件。
@fires	指示一个事件被触发。
@example	提供一个代码示例。
@description	提供一个更详细的描述。
@author	描述作者。
@version	描述版本。
@since	描述从哪个版本开始引入。
@deprecated	标记为废弃。

Vue 组件的 JSDoc 示例：

/**
 * @vue
 * @component MyButton
 * @description 一个简单的按钮组件。
 *
 * @prop {string} label  按钮的文本。
 * @prop {boolean} disabled  是否禁用按钮。
 * @emits click  当按钮被点击时触发。
 *
 * @example
 * <MyButton label="Click me" @click="handleClick" />
 */
export default {
  name: 'MyButton',
  props: {
    label: {
      type: String,
      required: true,
    },
    disabled: {
      type: Boolean,
      default: false,
    },
  },
  emits: ['click'],
  methods: {
    handleClick() {
      if (!this.disabled) {
        this.$emit('click');
      }
    },
  },
};

在这个例子中，我们使用了 @vue 和 @component 标签来标记这是一个 Vue 组件。然后，我们使用 @prop 标签来描述组件的 props，使用 @emits 标签来描述组件触发的事件。最后，我们使用 @example 标签来提供一个代码示例。

注意： JSDoc 并没有一个官方的 Vue 组件的标签。@vue 是一个约定俗成的标签，方便文档生成工具识别 Vue 组件。

第三部分：TypeScript 的使用方法

TypeScript 是一种静态类型的 JavaScript 超集。它提供了类型检查、接口、类等特性，可以帮助你编写更健壮、更易于维护的代码。

TypeScript 的基本语法：

interface User {
  name: string;
  age: number;
}

function greet(user: User): string {
  return `Hello, ${user.name}! You are ${user.age} years old.`;
}

const myUser: User = {
  name: 'Alice',
  age: 30,
};

console.log(greet(myUser));

在这个例子中，我们使用了 interface 关键字来定义一个 User 类型。然后，我们使用类型注解来指定函数 greet 的参数类型和返回值类型。最后，我们使用类型注解来指定变量 myUser 的类型。

Vue 组件的 TypeScript 示例：

import { defineComponent } from 'vue';

export default defineComponent({
  name: 'MyButton',
  props: {
    label: {
      type: String,
      required: true,
    },
    disabled: {
      type: Boolean,
      default: false,
    },
  },
  emits: ['click'],
  setup(props, { emit }) {
    const handleClick = () => {
      if (!props.disabled) {
        emit('click');
      }
    };

    return {
      handleClick,
    };
  },
});

在这个例子中，我们使用了 defineComponent 函数来定义一个 Vue 组件。我们使用了类型注解来指定 props 的类型。TypeScript 编译器会自动检查 props 的类型是否正确。

TypeScript 的优势：

• 类型安全： TypeScript 可以在编译时检查类型错误，避免运行时错误。
• 代码提示： TypeScript 可以提供更准确的代码提示，提高开发效率。
• 重构： TypeScript 可以更容易地重构代码，因为它可以在编译时检查类型是否一致。
• 可维护性： TypeScript 可以提高代码的可维护性，因为它使代码更易于理解和修改。

第四部分：选择你的武器库：文档生成工具

有了 JSDoc 或 TypeScript 注释，接下来就需要一个工具来将这些注释转换成漂亮的 API 文档。市面上有很多文档生成工具可供选择，例如：

• JSDoc: 官方的 JSDoc 工具，功能强大，配置灵活。
• TypeDoc: 专门为 TypeScript 设计的文档生成工具，可以生成非常漂亮的 API 文档。
• Storybook: 不仅仅是一个 UI 组件开发环境，还可以生成组件文档。
• VuePress: 一个 Vue 驱动的静态网站生成器，可以用来生成组件库的文档网站。
• Docsify: 一个神奇的文档站点生成器。

选择哪个工具取决于你的需求和偏好。

• 如果你只需要生成简单的 API 文档，并且已经在使用 JSDoc，那么 JSDoc 工具是一个不错的选择。
• 如果你使用 TypeScript，并且希望生成非常漂亮的 API 文档，那么 TypeDoc 绝对是首选。
• 如果你需要一个完整的组件开发环境，并且希望生成交互式的组件文档，那么 Storybook 是一个不错的选择。
• 如果你需要一个完整的文档网站，并且希望使用 Vue 来构建你的文档，那么 VuePress 或 Docsify 是一个不错的选择。

这里我们以 TypeDoc 为例，演示如何生成 API 文档。

1. 安装 TypeDoc：

npm install -D typedoc

2. 配置 TypeDoc：

创建一个 typedoc.json 文件，配置 TypeDoc 的选项。

{
  "entryPoints": ["./src/components"],
  "out": "./docs",
  "readme": "none",
  "name": "My Vue Component Library",
  "tsconfig": "./tsconfig.json"
}

• entryPoints: 指定要生成文档的入口文件。
• out: 指定文档的输出目录。
• readme: 指定 README 文件的路径，设置为 "none" 表示不使用 README 文件。
• name: 指定文档的标题。
• tsconfig: 指定 TypeScript 配置文件。

3. 生成文档：

在 package.json 文件中添加一个脚本：

{
  "scripts": {
    "docs": "typedoc"
  }
}

然后运行：

npm run docs

TypeDoc 就会自动生成 API 文档到 docs 目录下。

第五部分：让文档更上一层楼：添加示例和 Demo

仅仅有 API 文档是不够的。用户还需要看到组件的使用示例和 Demo，才能更好地理解组件的功能和用法。

1. 使用 Storybook:

Storybook 是一个非常流行的 UI 组件开发环境，可以用来生成交互式的组件文档。

• 安装 Storybook：

  npx sb init

• 编写 Story：

  在 src/stories 目录下创建 Story 文件，例如 MyButton.stories.js 或 MyButton.stories.ts:

  import MyButton from '../components/MyButton.vue';
  
  export default {
    title: 'MyButton',
    component: MyButton,
  };
  
  const Template = (args) => ({
    components: { MyButton },
    setup() {
      return { args };
    },
    template: '<MyButton v-bind="args" />',
  });
  
  export const Primary = Template.bind({});
  Primary.args = {
    label: 'Click me',
  };
  
  export const Disabled = Template.bind({});
  Disabled.args = {
    label: 'Click me',
    disabled: true,
  };

• 运行 Storybook：

  npm run storybook

  Storybook 就会自动启动，并显示你的组件。

2. 使用 VuePress 或 Docsify:

VuePress 和 Docsify 都可以用来构建组件库的文档网站。你可以在文档网站中添加组件的使用示例和 Demo。

• 在 VuePress 中，你可以使用 Vue 组件来构建你的 Demo。
• 在 Docsify 中，你可以使用 HTML、CSS 和 JavaScript 来构建你的 Demo。

第六部分：持续集成和文档自动化

为了保持文档的更新，你可以将文档生成过程集成到你的持续集成流程中。

• 每次代码提交时，自动生成 API 文档。
• 将生成的 API 文档部署到你的网站上。

例如，你可以使用 GitHub Actions 来实现文档自动化。

name: Generate Docs

on:
  push:
    branches:
      - main

jobs:
  docs:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: '16'
      - run: npm install
      - run: npm run docs
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs

这个 GitHub Actions 会在每次提交到 main 分支时，自动生成 API 文档，并将文档发布到 GitHub Pages。

总结

今天我们学习了如何为 Vue 组件库编写详细的 JSDoc 或 TypeScript 文档，并自动生成 API 文档。

• 选择你的武器：JSDoc vs TypeScript
• 使用 JSDoc 或 TypeScript 注释来描述你的代码。
• 选择你的武器库：文档生成工具 (JSDoc, TypeDoc, Storybook, VuePress, Docsify)
• 添加示例和 Demo，让文档更上一层楼。
• 使用持续集成来自动化文档生成过程。

希望今天的分享对大家有所帮助！记住，好的文档是组件库成功的关键！下次别人再问你组件怎么用的时候，甩给他一个链接，让他自己去看文档吧！

各位，下课！