1. 前言

在编码的过程中，很多情况下我们都有输出 api 文档的需求，因此本文将介绍如何使用 jsdoc 输出 api 文档。

2. jsdoc

JSDoc 是一个用于 JavaScript 的 API 文档生成器，类似于 Javadoc 或 phpDocumentor。可以将文档注释直接添加到源代码中，就在代码本身旁边。 JSDoc 工具将扫描源代码并生成 HTML 文档。

安装依赖包：
npm i -D jsdoc@3

2.1 创建配置文件

// jsdoc.js

module.exports = {
  recurseDepth: 10,
  source: {
    includePattern: '.+\\.(js|ts|md)$',
    excludePattern: '__',
  },
  sourceType: 'module',
  tags: {
    allowUnknownTags: true,
    dictionaries: ['jsdoc', 'closure'],
  },
  templates: {
    cleverLinks: false,
    monospaceLinks: false,
  },
  opts: {
    destination: './docs/',
  },
}

2.2 配置执行命令

// package.json

{
  // ...
  "scripts": {
    "jsdoc": "jsdoc -R README.md -c jsdoc.js tsc-out/**/*.js --verbose"
  }
  // ...
}

执行npm run jsdoc即可在“docs”生成 html 文档。

3. 生成 markdown 文档

从 jsdoc 注释的源代码生成 Markdown API 文档。用于将 API 文档注入项目 README 文件中。

安装依赖包：
npm i -D jsdoc-to-markdown@7

3.1 配置执行命令

// package.json

{
  // ...
  "scripts": {
    "jsdoc2md": "jsdoc2md tsc-out/**/*.js > docs.md"
  }
  // ...
}

4. DEMO

本小节将演示如何使用 jsdoc 语法编写 js 文件，详细用法请参阅 jsdoc 官方文档。

const os = require('os')
const path = require('path')

const LOCAL_OS_TYPE = os.type()
const LOCAL_HOSTNAME = os.hostname().toLowerCase()
const LOCAL_HOME_DIR = os.homedir()

/**
 * @class OSUtils
 * @classdesc OSUtils
 */
class OSUtils {
  /**
   * 定义操作系统类型
   * @static
   * @memberof OSUtils
   */
  static OS_TYPE = {
    MAC_OS: 'Darwin',
    LINUX: 'Linux',
    WINDOWS: 'Windows_NT',
  }

  /**
   * 判断是否是macOS
   * @static
   * @return {boolean}
   * @memberof OSUtils
   */
  static isMacOS() {
    return LOCAL_OS_TYPE === OSUtils.OS_TYPE.MAC_OS
  }

  /**
   * 判断是否是 linux
   * @static
   * @return {boolean}
   * @memberof OSUtils
   */
  static isLinux() {
    return LOCAL_OS_TYPE === OSUtils.OS_TYPE.LINUX
  }

  /**
   * 判断是否是 windows
   * @static
   * @return {boolean}
   * @memberof OSUtils
   */
  static isWindows() {
    return LOCAL_OS_TYPE === OSUtils.OS_TYPE.WINDOWS
  }
}

module.exports = OSUtils