前言:
在敏捷开发的过程中或者说是项目后期维护的过程中,文档是必不可少的,可以避免过多的交流从而加快项目的速度,今天介绍的就是一款基于前端的工具jsdoc,他能够根据代码中的注释很快生成API文档,只需要一个命令。
1.首先我这里推荐一个注释的快捷键工具,您可以在VS Code 中安装它。
插件名称:koroFileHeader
截图:
这个插件安装好后就可以使用了,鼠标点击js方法然后按 Ctrl+Alt+T ,就会自动生成注释,更多的使用方式可以在网上自行了解。
2.接下来我们安装jsdoc,您可以打开VS Code 的终端
输入命令:npm install jsdoc -g
3.安装好之后,你可以为你的Api函数添加注释,这时就可以使用上面的快捷键了。
我这里只写了参数和返回值,您也可以按照jsdoc的标准注释规格来描述更多的内容;
下面是我粘贴的一些jsdoc注释的关键字及说明,可以参考。
(1)对文件进行描述
@author —— 指定项目作者
@copyright —— 描述版权信息
@see —— 描述可以参考外部资源
@version —— 描述版本信息
@tutorial —— 插入一个指向教程的链接,作为文档的一部分
@since —— 描述该功能哪个版本哪个时间添加进来的
@summary —— 描述一个简写版本
@file —— 文件说明,在文件开头使用
@license —— 描述代码才有那种软件许可协议
(2)标注js使用方法
@returns —— 描述一个函数的返回值