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