JSDoc注釋規(guī)范是什么

小編給大家分享一下JSDoc注釋規(guī)范是什么，相信大部分人都還不怎么了解，因此分享這篇文章給大家參考一下，希望大家閱讀完這篇文章后大有收獲，下面讓我們一起去了解一下吧！

什么是 JSDoc

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

JSDoc 注釋規(guī)則

JSDoc注釋一般應(yīng)該放置在方法或函數(shù)聲明之前，它必須以/ **開始，以便由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 - 書本的標(biāo)題.
* @param {string} author - 書本的作者.
*/
functionBook(title, author){
    this.title=title;
    this.author=author;
}
Book.prototype={
/**
* 獲取書本的標(biāo)題
* @returns {string|*} 返回當(dāng)前的書本名稱
*/
getTitle:function(){
    returnthis.title;   
},
/**
* 設(shè)置書本的頁數(shù)
* @param pageNum {number} 頁數(shù)
*/
setPageNum:function(pageNum){
    this.pageNum=pageNum;   
}
};

@constructor 構(gòu)造函數(shù)聲明注釋

@constructor明確一個函數(shù)是某個類的構(gòu)造函數(shù)。

@param 參數(shù)注釋

我們通常會使用@param來表示函數(shù)、類的方法的參數(shù)，@param是JSDoc中最常用的注釋標(biāo)簽。參數(shù)標(biāo)簽可表示一個參數(shù)的參數(shù)名、參數(shù)類型和參數(shù)描述的注釋。如下所示：

/**
* @param {String} wording 需要說的句子
*/
functionsay(wording){
    console.log(wording);
}

@return 返回值注釋

@return表示一個函數(shù)的返回值，如果函數(shù)沒有顯示指定返回值可不寫。如下所示：

/*
* @return {Number} 返回值描述
*/

@example 示例注釋

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

/*
* @example
* multiply(3, 2);
*/

其他常用注釋

@overview對當(dāng)前代碼文件的描述。

@copyright代碼的版權(quán)信息。

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

@version當(dāng)前代碼的版本。

以上是“JSDoc注釋規(guī)范是什么”這篇文章的所有內(nèi)容，感謝各位的閱讀！相信大家都有了一定的了解，希望分享的內(nèi)容對大家有所幫助，如果還想學(xué)習(xí)更多知識，歡迎關(guān)注億速云行業(yè)資訊頻道！