很多人第一眼喜欢上idea或Webstorm,是其拥有非常强大的自动提示功能(js中的自动提示准确率和范围远远高过其他编辑器)。
但javascript太灵活了,又是弱类型语言,提示的准确度和详细度依然是个问题(比如,一个带参数的函数,Webstorm无法提示出参数的数据类型)。
Webstorm5.0引入JSdoc的标签支持,通过开发者自己给代码加上符合jsdoc要求的注释,来达到强化js自动提示的目标。
关于jsdoc,有不清楚的请看明河以前写的文章《使用jsdoc生成组件API文档—jsdoc实战》,如果你想知道如何编译出API文档,请看明河写的ant教程《ant结合jsdoc构建js文档—ant入门指南》。
随便写个类,没加任何jsdoc注释时
function
User(name){
this
.name= name;
}
User.prototype = {
render:
function
(){
},
getMoney:
function
(money){
return
money;
}
};
|
外部调用之:
var
minghe =
new
User(
'明河'
);
minghe.getMoney(1000);
|
在写这二行中,Webstorm给出User类和getMoney的提示,但如果getMoney的参数数据类型只能是数值型,Webstorm没给出对应的提示。
接下来我们给getMoney这个函数加上jsdoc。
(PS:Webstorm非常的知心,当你写好函数时候,输入“/**”加回车,会自动生成jsdoc格式的注释)
/**
*
* @param money
* @return {*}
*/
getMoney:
function
(money){
return
money;
}
|
我们补充些限制上去:
/**
*
* @param {Number} money 一个屌丝能有多少钱
* @return {Number}
*/
getMoney:
function
(money){
return
money;
}
|
做个测试:外部传入一个字符串作为参数
提示你传入的参数不是数值型!!
上面明河只是举了个简单的例子,来看下其他的demo。
先来看下一个带完成jsdoc注释的类,uploader中的queue。
利用jsdoc可以强化Structure的类成员的索引,有jsdoc补充后,Structure变得非常方便,我现在我用它来快速定位代码。
使用ctrl+F12快速打开Structure界面。
@extends :用于类继承关系的声明
@typedef:用于复杂数据类型的声明
明河费这么多口舌,只是传递一个信息:完善的注释对于前端而言非常重要,利用jsdoc,不只可以输出API文档,还可以给我们实际编码带来便利,何乐而不为呢?