jsdoc安装与配置

0 环境

本文档采用npm版本为6.11.3

jsdoc官网

1 使用NPM安装JSDoc

首先，新建一个工程目录，不妨为jsdoc_demo。创建完成后进入目录

执行

npm init -y

生成一个package.json文件

安装jsdoc

npm i -D jsdoc

package.json中会新增开发依赖配置项

2 配置

jsdoc需要一个配置文件，如果你不创建它，jsdoc会使用默认值

首先，在工程根目录创建一个文件jsdoc.json，并从官网复制默认内容进去

{
    "plugins": [],
    "recurseDepth": 10,
    "source": {
        "includePattern": ".+\\.js(doc|x)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    },
    "sourceType": "module",
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": ["jsdoc","closure"]
    },
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
    }
}

具体配置项请阅读官网配置说明，本文档不深究配置项。下面对该配置文件进行修改，修改后如下

{
    "plugins": ["plugins/markdown"],
    "source": {
        "include": ["src"],
        "includePattern": ".js$",
        "excludePattern": "(node_modules/|docs)"
    },
    "sourceType": "module",
    "templates": {
        "cleverLinks": true,
        "monospaceLinks": true
    },
    "opts": {
        "recurse": true,
        "destination": "./docs/"
    }
}

打开package.json文件，添加执行脚本，下面是脚本添加后的内容

 "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "doc": "jsdoc -c jsdoc.json"
  },

3 测试

按照配置，我们需创建名为src的源文件夹，该文件夹中的js文件将会自动生成文档。

我们在src下直接创建一个index.js文件。此时，文件中没有内容，但我们可以直接执行脚本测试。

执行

npm run doc

我们会发现工程根目录下多了一个docs文件夹，这是jsdoc按照配置文件的配置生成的。进入docs文件夹，直接打开index.html查看效果

文档成功生成，但除了模板啥内容没有

我们在index.js中添加一些内容

// @ts-check

/**
 * Student Name
 * @type {string}
 */
const studentName = 'John Doe';

然后再次执行生成文档的脚本，看下效果

完结。后面的开发按照规范写注释，即可快速生成文档。