jsDoc学习记录
一、安装
npm install -g jsdoc # 全局安装
二、书写规范
1. 常用
@file@fileoverview@overview文件开头提供文件说明@summary总结@author作者@copyright版权@version版本@license软件许可协议@description@desc描述
/**
*@file 这是文件描述
*@summary 描述的简要概括
*@author 作者
*@copyright 版权信息
*@version 版本
*@license 许可证
*/
/**
* 在开头可以省略@description，直接写描述
* @description 后面追加的描述会覆盖前文
*/
@example添加示例代码
/**
* @example <caption>Usage Example</caption>
* var h = sayHello();
* console.log(h);
*/
function sayHello () {
return 'Hello';
}
@access访问权限，常用以下缩写@private@protected@package@public
/** constructor */
function Thingy() {
/** @private */
var foo = 0;
/** @public */
this.bar = true;
/** @protected */
this._inner = 'OK';
}
@param@arg@argument函数参数的注释
/**
* @param {string} someBody - someone you want to say hello to. // 普通写法
* @param {string} someBody='John' - someone you want to say hello to. // 带默认值
* @param {string} [someBody] - someone you want to say hello to. // 可选参数
* @param {number|string} someBody - someone you want to say hello to. // 多类型
* @param {*} someBody - someone you want to say hello to. // 任意类型
* @param {...string} someBody - someone you want to say hello to. // 可重复
*/
function sayHello (someBody) {
return 'Hello ' + someBody;
}
@property对象属性详细说明
/**
* @namespace
* @property {object} defaults - The default values for parties.
* @property {number} defaults.players - The default number of players.
* @property {string} defaults.level - The default level for the party.
* @property {object} defaults.treasure - The default treasure.
* @property {number} defaults.treasure.gold - How much gold the party starts with.
*/
var config = {
defaults: {
players: 1,
level: 'beginner',
treasure: {
gold: 0
}
}
};
@typenullundefinednumberstringbooleansymbol?number可以是null和number!number非空number
@typdef自定义类型
/**
*@typedef {(number|string)} NumberLike
*/
@returns@return返回值
/**
*@returns {number}
*/
@throws@exception有可能的异常
/**
*@throws {InvalidTypeException}
*/
@class@constructor构造函数@constant@const常量@default@defaultvalue默认值
2. 其他
@alias别名@abstract抽象方法@virtual@async异步@arguments@extends继承@borrows借用已有文档@lends@callback回调@deprecated弃用@enum枚举变量集合@exports导出@external@host外部@function@func@method函数类型@readonly只读@requires依赖@generator生成器类型@yields@yield@global全局@hideconstructor隐藏构造函数@ignore忽略注释，注释不生成Doc@interface接口@implements接口实现@inheritdoc继承文档@inner内部对象，内部成员Parent~Child@instance实例Parent#Child@kind种类，常用以下缩写@class@constant@event@external@file@function@member@mixin@module@namespace@typedef
@listens@member@var成员@memberof@static静态成员@mixes被混入@mixin混入@namespace@override
三、生成文档
jsdoc yourFile.js