webstorm中生成jsdoc注释文档的方法
生成如下下图的文档格式
使用到的文档
- jsdoc非常简单易懂的使用方法
- 官方文档，详细看Block Tags，不知道有没有科学上网限制
- intellij的自定义模板方法，因为同为idea使用方式极为类似
步骤
- 完成jsdoc的安装并且检验是否安装成功
首先打开第一个文档，使用命令行安装
npm install -g jsdoc或者局部安装npm install jsdoc
安装完成之后复制文档jsdoc非常简单易懂的使用方法中的这段代码到你的js中
/**
* HelloWorld类存储一位客人的名字，并打招呼。
*/
class HelloWorld {
constructor(){
this.firstName = '';
this.lastName = '';
}
/**
* 设置客人的姓名
*
* @param {String} lastName 姓
* @param {String} firstName 名
*/
setName(lastName, firstName){
this.lastName = lastName;
this.firstName = firstName;
}
/**
* 获取客人的全名
*
* @return {String} 客人的姓名
*/
getFullName(){
return this.lastName + ' ' + this.firstName;
}
/**
* 向客人打招呼
*
*/
sayHello(){
console.log('Hello, ' + this.getFullName());
}
}
运行jsdoc + 你的文件路径
成功之后在目录中会生成一个out的文件夹
在浏览器中打开index.html就可以看到这样的界面
到这里说明jsdoc安装完成。
熟悉一下官方文档
现在可以大致看看官方文档中注释Block Tags有哪些，可以先试试-
结合webstorm食用口感更佳
我并不想在在每个js中手动写一长串的注释。。。（估计没人愿意吧）
这个地方就要使用到webstorm的自定义模板
打开我们最后一个文档intellij的自定义模板方法
打开webstorm
Settings-->Editor-->Live Templates
先点击javascript后点击+，然后添加完之后就出现我定义的method*的模板
关键是添加这个模板的过程：
这个内容有一些技巧在其中
/**
* @file: $file_name$
* @method $functionName$
* @param {type} argName - description
* @param {type} argName - description
* @param {type} argName - description
* @return {type} argName - description
* @description:
* @author: $USER$
* @date: $DATE$
*/
点击右边的按钮之后弹出
全部设置好之后再看看这个地方是不是忘了
-
试验一下效果，发现还差一点
我在某个js文件中输入method*然后tab就输出我的模板
发现method的$functionName$并没有出现，但是file的$file_name$出现了,试了下要在函数的内部使用才能生效
-
继续优化
每次在终端输命令好烦。。于是写进npm的script里面
之后每次写完就npm run doc
说明一下添加README.md是在第一文档中有写，就不赘述了
现在就试一下吧
自己也在摸索中，有很多不足请见谅
