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
}
}
};
@type
null
undefined
number
string
boolean
symbol
?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