JSDoc+规范

HBuilder JSDoc+规范

\n

目录

\n

介绍

\n

支持标签

\n

类型语法

\n

特殊类型

\n

介绍

\n

JSDoc有2个作用,导出API文档和明确代码类型,辅助代码提示。
JSDoc描述了函数或变量的功能、值域、示例等很多代码提示时需要的数据,还可以通过类型定义,给动态的JS变量或函数赋予明确的类型。
HBuilder支持JSDoc3的书写和解析,JSDoc 3详细的标签介绍及语法请参考JSDoc 3
但标准的JSDoc是不够的,为了提高JS代码类型解析的精确性和实现更强大的代码助手提示,我们扩展了JSDoc。

-对于普通开发者,书写JSDoc有助于代码可读性的提升,在很多要求严格的大公司,JSDoc是强制要求编写的。
完善的JSDoc也能让开发者自定义的函数在引用时得到更方便的代码提示。
-对于框架开发者,书写好的JSDoc是必须的,除了生成API手册,良好的JSDoc可以让框架在IDE里得到更好的提示。
-开发者们也可以给别人的JS框架补充JSDoc,以便在HBuilder里得到更好的提示。
如果你完成了某个框架的JSDoc,请提交到https://github.com/dcloudio/WebFrameworkGrammar,广大开发者都在期待你给大家带来的便利。
另外共享框架语法是可以获得HBuilder积分奖励的哦。

JSDoc写法

\n
/** 文档注释写在这里 ,生成JSDoc的快捷键是[Alt+shift+J]。 */。
\n

支持标签

\n

下面是HBuilder会解析的一些标签,对JS解析引擎确定变量类型时有一定的帮助。

@alias

\n

使用@alias可以给一个变量或者函数指定一个别名,代码提示时会提示该别名

语法
\n
@alias aliasName
\n
例子
\n
(function(){
/**
* @alias foo
*/
function _fooBar(){

}
window.foo = _fooBar;
})();
foo();
\n

@constructor

\n

使用@constructor可以标识一个函数是构造函数

语法
\n
@constructor
\n
例子
\n
/**
* @constructor
*/
function Animal(name,weight){
this.name = name;
this.weight = weight;
}
var animal = new Animal('恐龙',10000);
alert(animal.name);
\n

@description

\n

使用@description可以在代码提示时显示被描述变量或者函数的描述信息。

语法
\n
@description 描述内容
\n
例子
\n
/**
* @description 这是一个构造函数
* @constructor
*/
function Animal(name,weight){
this.name = name;
this.weight = weight;
}
\n
代码截图
\n

@example

\n

使用@example可以提示代码示例。

语法
\n
@example 示例内容
\n
例子
\n
/**
* @description 这是一个构造函数
* @example
* var animal = new Animal('恐龙',1000);
* @constructor
*/
function Animal(name,weight){
this.name = name;
this.weight = weight;
}
\n
代码截图
\n

@extends

\n

使用@extends用于标识继承于某个类型。

语法
\n
@extends {Type}
\n
例子
\n
/**
* @description 这是一个构造函数
* @example
* var animal = new Animal('恐龙',1000);
* @constructor
*/
function Animal(name,weight){
this.name = name;
this.weight = weight;

this.say = function(){}
}

/**
* @extends {Animal}
*/
function Dog(){
this.say = function(){
console.log(this.name+":wang wang wang ...");
}
}
Dog.prototype = new Animal();
var dog = new Dog();
dog.name = "gougou";
dog.say();
\n
代码截图
\n

@param

\n

使用@param可以描述一个函数的参数以及参数类型,HBuilder扩展了参数值域的写法(目前只支持字符串值域)

语法
\n
@param {Type[,Type,...]} ParameterName=[Value1|Value2[|Value3|...]] 参数描述
\n
例子
\n
/**
* 这是一个方法描述
* @param {String} method = [get|post] 可选值域包括get和post,get是直接请求,post是提交数据
*/
function Request(method) {}
\n
代码截图
\n

@property

\n

使用@property可以描述一个对象的属性

语法
\n
@property {Type[,Type,...]} propertyName 属性描述
\n
例子
\n
/**
* @property {IDString} id id元素
* @property {ClassString} classNames class样式
*/
var htmlOptions = {
id:null,
classNames:null
}
htmlOptions.id = "123";
htmlOptions.classNames = "arrow area"
\n
代码截图
\n

@return

\n

使用@return可以描述一个对象的属性

语法
\n
@return {Type[,Type,...]}
\n
例子
\n
/**
* @return {HTMLDocument}
*/
function getDocument() {
//some code
}
getDocument().getElementById("123");
\n
代码截图
\n

@type

\n

使用@type可以定义某个变量的类型

语法
\n
@type {Type[,Type,...]}
\n
例子
\n
/**
* @type {IDString}
*/
var htmlId = null;
htmlId = "123";
\n
代码截图
\n

类型语法

\n

在上述JSDoc语法使用时,我们经常看到类型。不管是@extends、@param、@property还是@type,都涉及类型语法,都有些什么类型呢?
HBuilder定义了一套非常完善的类型系统,包括各种类型的组合,在写类型时提供了丰富的智能提示。

单一的类型

\n
语法
\n
{TypeName}
\n
例子
\n
这里定义一个类型为Document的变量
/**
* @type {Document}
*/
var foo = null;
\n
代码截图
\n

多个类型

\n
语法
\n
{TypeName,TypeName[,TypeName,...]}
\n
例子
\n
这里定义一个类型为Document,HTMLElement的变量
/**
* @type {Document,HTMLElement}
*/
var foo = null;
\n
代码截图
\n

这里的foo既是Document,同时也是HTMLElement,同时可以提示这2种类型的属性和方法。

函数类型

\n
语法
\n
{Function(firstParamType,secParamType,...):returnType}
\n
例子
\n
//这里定义一个参数为Event的回调函数
/**
* @param {Function(Event)} callback
*/
function testCallBack(callback){}

//这里定义一个返回类型是参数为IDString返回值为HTMLElement的函数。
/**
* @return {Function(IDString):HTMLElement}
*/
function testFunctionReturn(){
return foo;
}
var rFunc = testFunctionReturn();
rFunc('id').getElementsByClassName('classA');
\n
代码截图
\n

特殊类型

\n

HBuilder为了对一些比较特殊的类型列表进行更智能的提示(比如id列表、样式列表、颜色列表、图片列表...的提示),特别定义了一批特殊类型列表。下面是扩展的各种类型的名字一览表。
IDString : 提示id的列表
ClassString : 提示class的列表
TagString : 提示html标签(tag)的列表
AttrString : 提示html标签属性的列表
AttrValueString : 提示html标签属性值域的列表
cssPropertyString : 提示css属性的列表
cssPropertyValueString : 提示css属性值域的列表
HTMLString : 能够支持在该字符串内部写html代码
CSSString : 能够支持在该字符串内部写css代码
URIString : 提示项目下所有文件的列表
ImageURIString : 提示项目下所有图片的列表
JSURIString : 提示项目下所有JS文件的列表
CSSURIString : 提示项目下所有CSS文件的列表
MultimediaString : 提示多媒体文件的列表
ColorString : 提示颜色的列表
FontString : 提示预置的字体列表
EventString : 提示事件名称的列表

下面是扩展的各种类型的代码提示样例截图。

IDString 提示id的列表。
\n

ClassString 提示class的列表。
\n

TagString 提示html标签(tag)的列表。
\n

AttrString 提示html标签属性的列表。
\n

AttrValueString 提示html标签属性值域的列表。
\n

cssPropertyString 提示css属性的列表。
\n

cssPropertyValueString 提示css属性值域的列表。
\n

HTMLString 能够支持在该字符串内部写html代码
\n

CSSString 能够支持在该字符串内部写css代码
\n

URIString 提示项目下所有文件的列表。
\n

ImageURIString 提示项目下所有图片的列表。
\n

JSURIString 提示项目下所有JS文件的列表。
\n

CSSURIString 提示项目下所有CSS文件的列表。
\n

MultimediaString 提示多媒体文件的列表。
\n

ColorString 提示颜色的列表。
\n

FontString 提示预置的字体列表。
\n

EventString 提示事件名称的列表。
\n


41 分享
僞柠檬 lison Think 风雪寻梦 fanker DCloud_heavensoft 皇虫 穿布鞋的coder lonjoy 威风堂堂 西德尼娅的骑士 烟雨梦霄云 苹果岸 白鸽 在路上丶 互帮互助 hoonng flax 早爱迟安 damdmen bzliukai 木子水吉 WendeSun _scott GIS小勤 化无 chen214123158 251508638@qq.com 清源先生 熊大大 1877682825@qq.com 573284970@qq.com 龙龙龍 FindFly 木头很努力 dudajun 1513323081@qq.com abiao 513238368@qq.com 1137283999@qq.com 杨小凡
runbin

runbin

真是越用越爱HBuilder.
0 赞 3 天前
525169571@qq.com

525169571@qq.com

我欲成仙,
0 赞 2017-03-02 18:29
abiao

abiao

不错
0 赞 2016-10-25 15:47
1513323081@qq.com

1513323081@qq.com

冒个泡,很赞的IDE。
0 赞 2016-10-25 14:00
miao.zilong@qq.com

miao.zilong@qq.com

感谢HBuilder 有人在拿它和编译型语言比 说不如编译型语言 建议这堆人先看下编译原理这些书!
0 赞 2016-10-20 19:40
舌尖跳舞

舌尖跳舞 回复 DCloud

代码跳转只能同一个文件中才可以
0 赞 2016-08-30 22:09
陈暖

陈暖

很赞, 我先用用看.
0 赞 2016-05-25 02:56
恨西园

恨西园

@example中
var animal = new Animal('恐龙',1000);
等号缺失
0 赞 2016-05-07 16:31
opri

opri

用不了?
/** 文档注释写在这里 ,生成JSDoc的快捷键是[Alt+shift+J]。 */
0 赞 2016-04-29 12:12
化无

化无

好用,太方便了~赞!都可以,蛮正常的~
0 赞 2016-02-17 16:24
aaaaaa211

aaaaaa211

bug 一大堆,唉
0 赞 2015-12-24 10:22
行旅

行旅

@param {String} 这个区分必传选传吗
0 赞 2015-12-22 18:05
嘎DO

嘎DO

Alt+shift+J 这个快捷键木有用啊~ 按了完全没反应,我也没开什么其他的软件啊 应该不会有热键冲突
0 赞 2015-11-24 12:26
杨

可是在amd模块里使用,根本没提示
0 赞 2015-11-16 13:07
DCloud

DCloud 回复 慕青儿

跳转一直都有啊,alt+鼠标左键,或者F12,或者跳转菜单里也有
0 赞 2015-10-28 03:59
askme

askme

确实很牛,注解式开发!
0 赞 2015-10-20 15:37
慕青儿

慕青儿

期待加入代码跳转功能
2 赞 2015-09-06 13:50
TianYA1991

TianYA1991

厉害,造福万民
1 赞 2015-08-12 14:52
苹果岸

苹果岸

非常赞,与时俱进
0 赞 2015-07-01 16:05
DIOGO

DIOGO

不错。。不错。。真的很不错的一个东西。
0 赞 2015-05-21 15:45
半调子前后端猿

半调子前后端猿 回复 八爪熊

它在提醒你电脑该换少年郎
0 赞 2015-04-21 11:04
无痕

无痕

由衷的感觉很赞
0 赞 2015-04-08 15:10
cj

cj

赞!
0 赞 2015-03-11 11:09
威风堂堂

威风堂堂

前辈们好厉害,支持!
1 赞 2015-03-04 11:25
DCloud_heavensoft

DCloud_heavensoft 回复 CodingSky

可不止引领一项技术,HBuilder的语法库、兼容库、js解析引擎,还有App的Native.js都是引领世界的:)
4 赞 2015-01-28 07:31
CodingSky

CodingSky

终于引领了一项技术~~~赞
1 赞 2015-01-22 10:21
DCloud_HB_WKP

DCloud_HB_WKP 回复 八爪熊

加我QQ:824810885 我帮你看看。
0 赞 2015-01-20 13:39
子非鱼

子非鱼

厉害啊。。支持HBuilder
1 赞 2015-01-20 11:01
丶Silence

丶Silence

赞啊
0 赞 2015-01-05 17:57

要回复文章请先登录注册