jsdoc学习笔记

javascript

工程管理

/**
 * @author - bornkiller <hjj491229492@hotmail.com>
 * @version - 1.0.0
 * @licence - private
 */

时效管理

• @since
• @todo
• @deprecated

JSDOC类型系统

内置类型

• {Number}
• {(Number|Object)}
• {?Number} Number or null
• {!Number} Not Number
• {...Number} 不定数量类型
• {Array.} 复合类型
• {Object.} 复合类型
• @param {Number} [param] 可选值
• @param {String} [name = value] 默认值

显式类型

部分时候，无法从结构中判定类型，比如interface的virtual comment，或者未立即赋值的变量声明，就需要使用显式的方式来指明。

/**
 * @type {(string|Array.)}
 * @function
 */
var foo;

定义类型

处理非原生类型时，可以采用自定义类型的方式来处理。注意，声明的class即是声明变量，同时声明类型。

声明普通类型。

/**
 * @typedef {object} AuthorityModel
 *
 * @property {string} account
 * @property {string} password
 *
 * @description - 远程登录信息结构
 */

在彻底promise化之后，回调函数甚少用到。

/**
 * @callback authorityCallback
 *
 * @param {number} responseCode
 * @param {string} responseMessage
 *
 * @description - This callback is displayed as a global member.
 */

事件在部分项目中还是较多使用。

/**
 * @event HeroUpdate
 * @type {object}
 *
 * @property {string} name
 * @property {number} age
 *
 * @description - Children event
 */

使用自定义事件注释的方式有触发与处理。

/**
 * Fire HeroUpdate sync.
 *
 * @fires HeroUpdate
 */
Hurl.prototype.snowball = function() {
  this.emit('HeroUpdate', {name: 'kevin', age: 25});
};

从道理上来说，可以配合callback同时使用。

/**
 * Catch HeroUpdate sync.
 *
 * @listens HeroUpdate
 */
function handleHeroUpdate(hero) {
  console.log(hero);
}

面向对象

可访问性

主要包含五类，private, protect, public, static, abstract。前三类粗放式抽象为@access。

/**
 * @description - validate email format
 *
 * @instance
 * @function
 * @name Validator#isValidEmail
 * 
 * @param {string} email
 * @return {boolean}
 */
/**
 * @description - validate phone format
 *
 * @inner
 * @function
 * @name Validator~isValidPhone
 *
 * @param {string} phone
 * @return {boolean}
 */
 /**
  * @description - Generic dairy product.
  * @constructor
  */
function DairyProduct() {}
/**
 * Check whether the dairy product is solid at room temperature.
 * @abstract
 * @return {boolean}
 */
DairyProduct.prototype.isSolid = function() {
    throw new Error('must be implemented by subclass!');
};

继承

接口实现。

/**
 * Class representing a color with transparency information.
 *
 * @class
 * @implements {Color}
 */
function TransparentColor() {}
// inherits the documentation from `Color#rgb`
TransparentColor.prototype.rgb = function() {};
/**
 * @description - Get the color as an array of red, green, blue, and alpha values.
 *
 * @return {Array<number>} An array containing the red, green, blue, and alpha
 * values, in that order.
 */
TransparentColor.prototype.rgba = function() {};

方法复写。

/**
 * @description Abstract class representing a network connection.
 * @class
 */
function Connection() {}
/**
 * @description - Open the connection.
 */
Connection.prototype.open = function() {};
/**
 * @description Class representing a socket connection.
 * @class
 * @extend Connection
 */
function Socket() {}
/**
 * @description - Open the socket.
 * @override
 */
Socket.prototype.open = function() {};

模块化

• @module
• @export
• @requires
• @external

错误处理

• @throws
• @exception

内联型

• {@link }
• {@tutorials }