uni-app JSDoc+规范

HBuilder JSDoc+规范

目录

• 介绍
• 支持标签
• 类型语法
• 特殊类型

介绍

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的快捷操作是敲/**回车。 */

支持标签

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

@alias

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

语法

[@alias](/user/alias) aliasName

例子

(function(){
    /**
     * [@alias](/user/alias) foo
     */
    function _fooBar(){}

    window.foo = _fooBar;
})();

foo();

@constructor

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

语法

[@constructor](/user/constructor)

例子

/**
 * [@constructor](/user/constructor)
 */
function Animal(name,weight){
    this.name = name;
    this.weight = weight;
}

var animal = new Animal('恐龙',10000);
alert(animal.name);

@description

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

语法

[@description](/user/description) 描述内容

例子

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

@example

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

语法

[@example](/user/example) 示例内容

例子

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

@extends

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

语法

[@extends](/user/extends) {Type}

例子

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

    this.say = function(){}
}

/**
 * [@extends](/user/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](/user/param) {Type[,Type,...]} ParameterName=[Value1|Value2[|Value3|...]] 参数描述

例子

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

@property

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

语法

[@property](/user/property) {Type[,Type,...]} propertyName 属性描述

例子

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

@return

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

语法

[@return](/user/return) {Type[,Type,...]}

例子

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

@type

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

语法

[@type](/user/type) {Type[,Type,...]}

例子

/**
 * [@type](/user/type) {IDString}
 */
var htmlId = null;
htmlId = "123";

类型语法

在上述JSDoc语法使用时，我们经常看到类型。不管是@extends、@param、@property还是@type，都涉及类型语法，都有些什么类型呢？

HBuilder定义了一套非常完善的类型系统，包括各种类型的组合，在写类型时提供了丰富的智能提示。

单一的类型

语法

{TypeName}

例子

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

多个类型

语法

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

例子

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

函数类型

语法

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

例子

//这里定义一个参数为Event的回调函数
/**
 * [@param](/user/param) {Function(Event)} callback
 */
function testCallBack(callback){}

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