DCloud
DCloud
  • 发布:2014-12-26 20:20
  • 更新:2023-10-07 17:13
  • 阅读:178903

JSDoc+规范

分类:HBuilder

HBuilder JSDoc+规范

###目录
####介绍
####支持标签
####类型语法
####特殊类型

###介绍 {#intro}

JSDoc有2个作用,导出API文档和明确代码类型,辅助代码提示。
JSDoc描述了函数或变量的功能、值域、示例等很多代码提示时需要的数据,还可以通过类型定义,给动态的JS变量或函数赋予明确的类型。
HBuilder/HBuilderX支持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写法

/** 文档注释写在这里 ,生成JSDoc的快捷操作是敲/**回车。 */。

###支持标签 {#support_tags}

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

####@alias

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

#####语法

@alias aliasName

#####例子

(function(){  
/**  
 * @alias foo  
 */  
function _fooBar(){  
	  
}  
window.foo = _fooBar;  
})();  
foo();

####@constructor

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

#####语法

@constructor

#####例子

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

####@description

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

#####语法

@description 描述内容

#####例子

/**  
 * @description 这是一个构造函数  
 * @constructor  
 */  
function Animal(name,weight){  
	this.name = name;  
	this.weight = weight;  
}

#####代码截图

####@example

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

#####语法

@example 示例内容

#####例子

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

#####代码截图

####@extends

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

#####语法

@extends {Type}

#####例子

/**  
 * @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();

#####代码截图

####@param

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

#####语法

@param {Type[,Type,...]} ParameterName=[Value1|Value2[|Value3|...]] 参数描述

#####例子

/**  
 * 这是一个方法描述  
 * @param {String} method = [get|post] 可选值域包括get和post,get是直接请求,post是提交数据  
 */  
function Request(method) {}

#####代码截图

####@property

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

#####语法

@property {Type[,Type,...]} propertyName 属性描述

#####例子

/**  
 * @property {IDString} id id元素  
 * @property {ClassString} classNames class样式  
 */  
var htmlOptions = {  
	id:null,  
	classNames:null  
}  
htmlOptions.id = "123";  
htmlOptions.classNames = "arrow area"

#####代码截图

####@return

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

#####语法

@return {Type[,Type,...]}

#####例子

/**  
 * @return {HTMLDocument}  
 */  
function getDocument() {  
	//some code  
}  
getDocument().getElementById("123");

#####代码截图

####@type

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

#####语法

@type {Type[,Type,...]}

#####例子

/**  
 * @type {IDString}  
 */  
var htmlId = null;  
htmlId = "123";

#####代码截图

###类型语法 {#type_syntax}

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

#####语法

{TypeName}

#####例子

这里定义一个类型为Document的变量  
/**  
 * @type {Document}  
 */  
var foo = null;

#####代码截图

####多个类型

#####语法

{TypeName,TypeName[,TypeName,...]}

#####例子

这里定义一个类型为Document,HTMLElement的变量  
/**  
 * @type {Document,HTMLElement}  
 */  
var foo = null;

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

####函数类型

#####语法

{Function(firstParamType,secParamType,...):returnType}

#####例子

//这里定义一个参数为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');

#####代码截图

###特殊类型 {#spec_types}

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的列表。

#####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 提示事件名称的列表。

53 关注 分享
僞柠檬 lison Think 风雪寻梦 fanker DCloud_heavensoft 皇虫 穿布鞋的coder lonjoy 威风堂堂 西德尼娅的骑士 烟雨梦霄云 苹果岸 白鸽 在路上丶 互帮互助 hoonng flax 早爱迟安 damdmen bzliukai 木子水吉 WendeSun _scott GIS小勤 化无 chen214123158 2***@qq.com 清源先生 熊大大 1***@qq.com 5***@qq.com 龙龙龍 FindFly 木头很努力 dudajun 1***@qq.com abiao 雪之梦技术驿站 1***@qq.com 杨小凡 5***@qq.com Trust b***@163.com 1***@qq.com 1***@sina.com 2***@qq.com 1***@qq.com f***@qq.com 1***@163.com

要回复文章请先登录注册

7***@qq.com

7***@qq.com

回复 DCloud_heavensoft :
额,我就是用的HBuilder尝试的,用的Mac的最新版的HBuilder。尝试了没有效果,不知道是不是快捷键冲突还是啥问题。
2018-12-29 10:14
DCloud_heavensoft

DCloud_heavensoft

回复 7***@qq.com :
这个是HBuilder的,HBuilderX还不支持快捷生成jsdoc
2018-12-27 01:41
7***@qq.com

7***@qq.com

/** 文档注释写在这里 ,生成JSDoc的快捷键是[Alt+shift+J]。 */
为何快捷键不起作用呢
2018-12-26 17:22
2***@qq.com

2***@qq.com

牛皮 牛皮
2018-12-08 09:47
诺碳

诺碳

HBuilderX 不支持这个嘛?
2018-09-27 11:55
w***@outlook.com

w***@outlook.com

回复 行旅 :
选传自己添加一个中括号就行了
2018-07-26 17:54
烫烫烫烫烫烫

烫烫烫烫烫烫

可不可以支持
/**
*@param {Object} param1 ...
**/
var fun = function(){console.log(arguments)};
这种样式的写法提示,T_T。
2018-07-10 17:38
田康华

田康华

引入的js文件没有作用么?
2018-03-28 16:32
9***@qq.com

9***@qq.com

牛逼啊 我的H-builder~
2017-09-25 11:23
前进星空

前进星空

怎么导出jsdoc?
2017-08-20 00:09