前端架構之路（4） - 前端開發文檔

時間 2021-02-18

標籤 javascript css html 前端 java git github json markdown 編輯器欄目系統架構简体版

原文原文鏈接

前端開發文檔

1. 爲何須要「前端開發文檔」

上一節講到開發規範，不以規矩，不成方圓，團隊開發離不開規範，這一節講的開發文檔是對開發規範的一個補充。javascript

從目的上講，規範與文檔都是爲了下降團隊的協做成本和維護成本，提升開發效率和質量，保證不會由於開發人員的變更而產生較大的影響。css

2. 哪些須要造成文檔

2.1 註釋（只討論 `js`）

隨着前端的發展，文檔已經慢慢的變得不可或缺了，並由社區的努力而造成了 JSDoc，相似 JavaDoc 和 PHPDoc。html

2.1.1 什麼是 JSDoc

JSDoc 是一個根據 javascript 文件中註釋信息，生成 JavaScript 應用程序或庫、模塊的 API 文檔的工具。你可使用他記錄如：命名空間，類，方法，方法參數等，而且不少編輯器和 IDE 都是直接支持智能提示的。前端

2.1.2 JSDoc 註釋示例

JSDoc 註釋通常應該放置在方法或函數聲明以前，它必須以 /** 開始，其餘任何以 /*，/*** 或者超過3個星號的註釋，都將被JSDoc解析器忽略。例如：java

/**
 * 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;
    },
    /**
     * 設置書本的頁數
     * @param pageNum {number} 頁數
     */
    setPageNum:function(pageNum){
        this.pageNum=pageNum;
    }
};

2.1.3 JSDoc 標籤一覽

{@link: ...}, {@linkplain: ...}, {@linkcode: ...}, {@tutorial: ...}: 內聯標籤
@abstract: 抽象，必須由繼承者實現（或者覆蓋）
@access: 訪問級別（private、public或者protected）
@alias: 別名
@augments: 參數
@author: 做者
@borrows: 借用
@callback: 回調函數
@classdesc: 類描述
@constant: 常量
@constructor: 構造函數，可使用new建立一個實例
@constructs: 構造
@copyright: 版權
@default: 默認值
@deprecated: 棄用的
@desc: 描述
@enum: 枚舉值
@event: 事件
@example: 範例
@exports: 模塊導出（模塊化）
@external: 外部模塊（模塊化）
@file: 文件
@fires: 可觸發的事件
@global: 全局對象
@ignore: 忽略
@inner: 內聯對象
@instance: 實例
@kind: 標識類型
@lends: 遍歷屬於同一個標識的全部屬性
@license: 軟件受權
@link: 內聯
@member: 成員
@memberof: 屬於某成員
@method: 方法
@mixes: 合併
@mixin: 最小化
@module: 模塊（模塊化）
@name: 名稱
@namespace: 命名空間
@param: 參數
@private: 私有的（訪問控制）
@property: 屬性
@protected: 受保護的（訪問控制）
@public: 公開的（訪問控制）
@readonly: 只讀的
@requires: 依賴（模塊化）
@return: 返回值
@see: 引用
@since: 開始於
@static: 靜態的
@summary: 概述
@this: 解釋this關鍵字
@throws: 可能拋出的異常
@todo: 待辦事項
@tutorial: 引用指導手冊
@type: 類型
@typedef: 自定義類型
@variation: 區分不一樣的對象具備相同名稱的
@version: 版本

2.1.4 把註釋生成文檔的工具

jsdoc: 官方提供的工具
documentation.js: 另一個可供選擇的工具，支持生成 html，markdown， json
dox: tj 大神的做品

2.2 業務邏輯、更新日誌與備註

另一個須要記錄的信息就是業務邏輯、更新日誌與備註。git

2.2.1 業務邏輯

有些比較複雜的業務邏輯不太適合放在註釋裏面，須要單獨寫邏輯文檔，以備後面查看。github

有時候，有些邏輯並非簡單的用文字描述就能說的清楚的，還須要圖表或者思惟導圖的輔助。json

2.2.2 更新日誌

更新日誌也是一個比較重要文檔，可以方便查找更新狀態、時間、開發人員等。markdown

2.2.3 備註

若是有額外的一些信息，須要用文檔備註一下。編輯器

3. 後續

上一篇：前端開發規範

下一篇：構建工具 for teamwork

參考文章：

JSDoc 中文文檔

更多博客，查看 https://github.com/senntyou/blogs

做者：深予之 (@senntyou)

版權聲明：自由轉載-非商用-非衍生-保持署名（創意共享3.0許可證）

相關文章

相關標籤/搜索

前端開發-EasyUI

Web 前端開發

web前端開發

每日一句

每一个你不满意的现在，都有一个你没有努力的曾经。

最新文章

本站公眾號

歡迎關注本站公眾號,獲取更多信息

相關文章

>>更多相關文章<<