前端開發(fā)文檔
1. 為什么需要 “前端開發(fā)文檔”
上一節(jié)講到開發(fā)規(guī)范幌绍，不以規(guī)矩署鸡，不成方圓般贼，團隊開發(fā)離不開規(guī)范，這一節(jié)講的開發(fā)文檔是對開發(fā)規(guī)范的一個補充劣挫。
從目的上講，規(guī)范與文檔都是為了降低團隊的協(xié)作成本和維護成本东帅，提高開發(fā)效率和質量压固，保證不會因為開發(fā)人員的變動而產(chǎn)生較大的影響。
2. 哪些需要形成文檔
2.1 注釋（只討論 js）
隨著前端的發(fā)展靠闭，文檔已經(jīng)慢慢的變得不可或缺了帐我，并由社區(qū)的努力而形成了 JSDoc，類似 JavaDoc 和 PHPDoc愧膀。
2.1.1 什么是 JSDoc
JSDoc 是一個根據(jù) javascript 文件中注釋信息拦键，生成 JavaScript 應用程序或庫、模塊的 API 文檔 的工具檩淋。你可以使用他記錄如：命名空間芬为，類，方法，方法參數(shù)等媚朦，并且很多編輯器和 IDE 都是直接支持智能提示的氧敢。
2.1.2 JSDoc 注釋示例
JSDoc 注釋一般應該放置在方法或函數(shù)聲明之前，它必須以 /** 開始莲镣，其他任何以 /*福稳，/*** 或者超過3個星號的注釋，都將被JSDoc解析器忽略瑞侮。例如：
/**
* Book類的圆，代表一個書本.
* @constructor
* @param {string} title - 書本的標題.
* @param {string} author - 書本的作者.
*/
function Book(title, author) {
this.title=title;
this.author=author;
}
Book.prototype={
/**
* 獲取書本的標題
* @returns {string|*}
*/
getTitle:function(){
return this.title;
},
/**
* 設置書本的頁數(shù)
* @param pageNum {number} 頁數(shù)
*/
setPageNum:function(pageNum){
this.pageNum=pageNum;
}
};
2.1.3 JSDoc 標簽一覽
-
{@link: ...}, {@linkplain: ...}, {@linkcode: ...}, {@tutorial: ...}: 內聯(lián)標簽 -
@abstract: 抽象，必須由繼承者實現(xiàn)（或者覆蓋） -
@access: 訪問級別（private半火、public或者protected） -
@alias: 別名 -
@augments: 參數(shù) -
@author: 作者 -
@borrows: 借用 -
@callback: 回調函數(shù) -
@classdesc: 類描述 -
@constant: 常量 -
@constructor: 構造函數(shù)越妈，可以使用new創(chuàng)建一個實例 -
@constructs: 構造 -
@copyright: 版權 -
@default: 默認值 -
@deprecated: 棄用的 -
@desc: 描述 -
@enum: 枚舉值 -
@event: 事件 -
@example: 范例 -
@exports: 模塊導出（模塊化） -
@external: 外部模塊（模塊化） -
@file: 文件 -
@fires: 可觸發(fā)的事件 -
@global: 全局對象 -
@ignore: 忽略 -
@inner: 內聯(lián)對象 -
@instance: 實例 -
@kind: 標識類型 -
@lends: 遍歷屬于同一個標識的所有屬性 -
@license: 軟件授權 -
@link: 內聯(lián) -
@member: 成員 -
@memberof: 屬于某成員 -
@method: 方法 -
@mixes: 合并 -
@mixin: 最小化 -
@module: 模塊（模塊化） -
@name: 名稱 -
@namespace: 命名空間 -
@param: 參數(shù) -
@private: 私有的（訪問控制） -
@property: 屬性 -
@protected: 受保護的（訪問控制） -
@public: 公開的（訪問控制） -
@readonly: 只讀的 -
@requires: 依賴（模塊化） -
@return: 返回值 -
@see: 引用 -
@since: 開始于 -
@static: 靜態(tài)的 -
@summary: 概述 -
@this: 解釋this關鍵字 -
@throws: 可能拋出的異常 -
@todo: 待辦事項 -
@tutorial: 引用指導手冊 -
@type: 類型 -
@typedef: 自定義類型 -
@variation: 區(qū)分不同的對象具有相同名稱的 -
@version: 版本
2.1.4 把注釋生成文檔的工具
- jsdoc: 官方提供的工具
-
documentation.js: 另外一個可供選擇的工具，支持生成
html钮糖，markdown梅掠，json - dox: tj 大神的作品
2.2 業(yè)務邏輯、更新日志與備注
另外一個需要記錄的信息就是業(yè)務邏輯店归、更新日志與備注阎抒。
2.2.1 業(yè)務邏輯
有些比較復雜的業(yè)務邏輯不太適合放在注釋里面，需要單獨寫邏輯文檔消痛，以備后面查看且叁。
有時候，有些邏輯并不是簡單的用文字描述就能說的清楚的秩伞，還需要圖表或者思維導圖的輔助逞带。
2.2.2 更新日志
更新日志也是一個比較重要文檔，能夠方便查找更新狀態(tài)纱新、時間展氓、開發(fā)人員等。
2.2.3 備注
如果有額外的一些信息脸爱，需要用文檔備注一下遇汞。
3. 后續(xù)
上一篇：前端開發(fā)規(guī)范
參考文章：
更多博客，查看 https://github.com/senntyou/blogs
版權聲明：自由轉載-非商用-非衍生-保持署名（創(chuàng)意共享3.0許可證）
