jsdoc安装与配置

0 环境

本文档采用npm版本为6.11.3

jsdoc官网

1 使用NPM安装JSDoc

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

执行

npm init -y

jsdoc安装与配置

生成一个package.json文件

安装jsdoc

npm i -D jsdoc

jsdoc安装与配置

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

jsdoc安装与配置

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

jsdoc安装与配置

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

jsdoc安装与配置

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

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

// @ts-check

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

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

jsdoc安装与配置

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

上一篇:"/etc/docker/daemon.json" E212: Can't open file for writing


下一篇:使用echarts绘制geo地图