JSDoc 注釋規范

JSDoc 注釋規范

什么是 JSDoc

JSDoc 是一個根據 JavaScript 文件中注釋信息,生成 JavaScript 應用程序或模塊的API文檔的工具。你可以使用 JSDoc 標記如:命名空間方法方法參數等。從而使開發者能夠輕易地閱讀代碼,掌握代碼定義的類和其屬性和方法,從而降低維護成本,和提高開發效率。

JSDoc 注釋規則

JSDoc注釋一般應該放置在方法或函數聲明之前,它必須以/ **開始,以便由JSDoc解析器識別。其他任何以??/*??,??/***??或者超過3個星號的注釋,都將被JSDoc解析器忽略。如下所示:

/*

**一段簡單的 JSDoc 注釋。

*/

JSDoc 的注釋效果

假如我們有一段這樣的代碼,沒有任何注釋,看起來是不是有一定的成本。

functionBook(title, author){

? ? ? this.title=title;

? ? ? this.author=author;

}

Book.prototype={

? ? ? getTitle:function(){

????????returnthis.title;? ?

? ? ? },

setPageNum:function(pageNum){

? ? ? this.pageNum=pageNum;? ?

}

};

如果使用了 JSDoc 注釋該代碼后,代碼的可閱讀性就大大的提高了。

/**

* Book類,代表一個書本.

* @constructor

* @param {string} title - 書本的標題.

* @param {string} author - 書本的作者.

*/

functionBook(title, author){

????this.title=title;

? ? this.author=author;

}

Book.prototype={

/**

* 獲取書本的標題

* @returns {string|*} 返回當前的書本名稱

*/

getTitle:function(){

????returnthis.title;? ?

},

/**

* 設置書本的頁數

* @param pageNum {number} 頁數

*/

setPageNum:function(pageNum){

????this.pageNum=pageNum;? ?

}

};

@constructor 構造函數聲明注釋

@constructor明確一個函數是某個類的構造函數。

@param 參數注釋

我們通常會使用@param來表示函數、類的方法的參數,@param是JSDoc中最常用的注釋標簽。參數標簽可表示一個參數的參數名參數類型參數描述的注釋。如下所示:

/**

* @param {String} wording 需要說的句子

*/

functionsay(wording){

????console.log(wording);

}

@return 返回值注釋

@return表示一個函數的返回值,如果函數沒有顯示指定返回值可不寫。如下所示:

/*

* @return {Number} 返回值描述

*/

@example 示例注釋

@example通常用于表示示例代碼,通常示例的代碼會另起一行編寫,如下所示:

/*

* @example

* multiply(3, 2);

*/

其他常用注釋

@overview對當前代碼文件的描述。

@copyright代碼的版權信息。

@author []代碼的作者信息。

@version當前代碼的版本。

更多參考

如果想了解更多的 JSDoc 注釋的內容,可參考下面的鏈接。

JSDoc 文檔

?著作權歸作者所有,轉載或內容合作請聯系作者
平臺聲明:文章內容(如有圖片或視頻亦包括在內)由作者上傳并發布,文章內容僅代表作者本人觀點,簡書系信息發布平臺,僅提供信息存儲服務。

推薦閱讀更多精彩內容

  • 原文: https://github.com/ecomfe/spec/blob/master/javascript...
    zock閱讀 3,393評論 2 36
  • Spring Cloud為開發人員提供了快速構建分布式系統中一些常見模式的工具(例如配置管理,服務發現,斷路器,智...
    卡卡羅2017閱讀 134,869評論 18 139
  • 第2章 基本語法 2.1 概述 基本句法和變量 語句 JavaScript程序的執行單位為行(line),也就是一...
    悟名先生閱讀 4,195評論 0 13
  • 伏爾加河上的纖夫 背著沉重的枷鎖 漠然地注視著腳下 偶爾望一望遠方 茫然 汗水滴落的土地 澆灌不出希望 背著生活那...
    亞民閱讀 231評論 0 0
  • 故事從女主的契約結婚開始。整部劇充滿女主的各種腦洞。 新恒.結衣的造型也很美。劇終也有很多亮點。 ...
    桃子的小站閱讀 719評論 2 1