| 实用

jsDoc那些事儿

历史原因

  • 首先是因为项目的原因，封装了很多util方法所以在使用的时候加一个jsdoc会用起来更方便

  • js本身是弱类型语言，有时候在传参调用的时候会出现类型的错误

  • 在以前的项目中，使用过jsdoc，不过写的不算特别规范，所以最近潜心研究一波

第一步(function)

在使用jsdoc之前，你必须为你的方法写上jsdoc的注释

如：

1
2
3
4
5
6
7
8
9
10
/**
 * @description 校验传入的路径是否是一个合法的url
 * @export {Function} isUrl
 * @param {String} path 待检测的url
 * @returns {Boolean} true or false
 */
export function isUrl(path) {
  const reg = /xxxxxx/
  return reg.test(path);
}

在上面的实例中，就给出了jsdoc

其中

1
2
3
4
5
6
/**
 * @description 对函数的描述
 * @export {Function} 对导出内容的描述
 * @param {String} path 对参数的表述
 * @returns {Boolean} 对返回值的描述
 */

第二步(arrow function)

在对箭头函数生成jsdoc的HTML文档的时候发现了一个致命的错误

生成的描述并不是我们想要的

这个时候我去查了github issue传送门

按照最后一个人所提示的方法进行了修改

1
2
3
4
5
6
7
/**
 * @method
 * @description 将分转换为元
 * @param {Number} val 金额 分
 * @returns {Number} 返回金额 元
 */
export const getPrice = val => val / 100;

在jsdoc的头部加上了@method这个注释

这个时候打包出来的文档就能正确显示了

第三步(全局安装)

  • 安装jsdoc 执行npm install jsdoc -g

  • 进入项目的根目录 在项目的根目录执行 jsdoc src/demo.js 后面这个路径就是你想要生成文档的js文件所在的路径

  • 执行成功之后 会在你的根目录生成一个out文件夹 从index.html进入你就会看见你生成的方法

第四步(在项目内处理)

  • 安装jsdoc 执行npm install jsdoc --save-dev

  • 在package.json里的script里添加一个批量生成的脚本"build:doc": "jsdoc -c jsdoc.json"

  • 还需要在根目录下创建一个jsdoc.json的文件，配置如下：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    {
      "source": {
        "include": ["src/utils/utils.js", "src/utils/download.js"],
        "exclude": []
      },
      "opts": {
        "encoding": "utf8",
        "destination": "./docs/",
        "recurse": true,
        "verbose": true
      }
    }
    • source: 表示传递给 JSDOC 的文件
    • include: 表示 JSDOC 需要扫描哪些文件
    • exclude: 表示 JSDOC 需要排除哪些文件
    • opts: 表示传递给 JSDOC 的选项
    • encoding: 读取文件的编码，默认是 utf8
    • destination: 生成文档的路径，默认是 ./out/
    • recurse: 运行时是否递归子目录
    • verbose: 运行时是否输出详细信息，默认是 false
ESC