DCloud JSDoc+ 代码规范

发布于 2021-10-21 12:24:33 字数 11276 浏览 1348 评论 0

介绍

编写 JSDoc 是为了增强代码的可读性，以及方便导出API文档。它的规范可参考 JSDoc 3

对于代码规范要求高的工程师和JS框架的开发者，熟悉JSDoc是必须的技能。如下是一段JSDoc示例

/**
	* 这个函数的用途写在这里
	* @param {Number} p 这个参数的解释在这里
*/
function foo(p) {
	
}

Javascript属于无类型的语言，这对于开发者入门很方便。但对于框架的开发者和IDE的开发者，缺少类型描述有很多不便。
其实利用JSDoc稍作扩展，我们可以把它用于类型和值域定义，进而用于代码提示和语法分析。
这样框架的使用者可以在IDE里方便的使用代码提示和语法错误分析功能。
这就是JSDoc+规范诞生的原因。

HBuilder 是已经支持 JSDoc+ 规范的 IDE，以下均以 HBuilder 为例介绍 JSDoc 的用法。

JSDoc 写法

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

支持标签

下面是 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";

代码截图

类型语法

在上述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');