《編寫可維護的JavaScript》——2.4 文檔注釋

本節書摘來自異步社群《編寫可維護的javascript》一書中的第2章，第2.4節，作者：【美】nicholas c. zakas著，更多章節内容可以通路雲栖社群“異步社群”公衆号檢視

從技術的角度講，文檔注釋并不是javascript的組成部分，但它們是一種普遍的實踐。文檔注釋有很多種格式，但最流行的一種格式來自于javadoc文檔格式：多行注釋以單斜線加雙星号（/**）開始，接下來是描述資訊，其中使用@符号來表示一個或多個屬性。來看一段來自yui的源碼的例子。

<code>/**</code>

傳回一個對象，這個對象包含被提供對象的所有屬性。

後一個對象的屬性會覆寫前一個對象的屬性。

傳入一個單獨的對象，會建立一個它的淺拷貝（shallow copy）。

yui類庫使用它自己的一個名叫yuidoc的工具來根據這些注釋生成文檔。但是，它的格式幾乎和jsdoc toolkit（類庫無關的）一模一樣，在開源項目中jsdoc toolkit的應用非常廣泛，包括google内部的很多開源項目。yuidoc和jsdoc toolkit之間的重要差別是，yuidoc同時支援文檔注釋中的html和markdown格式，而jsdoc toolkit隻支援html。

這裡強烈推薦你使用文檔生成工具來為你的javascript生成文檔。javascript代碼注釋必須符合你所用的工具支援的格式，但很多文檔生成工具都支援javadoc風格的文檔注釋。當使用文檔注釋時，你應當確定對如下内容添加注釋。

所有的方法

應當對方法、期望的參數和可能的傳回值添加注釋描述。

所有的構造函數

應當對自定義類型和期望的參數添加注釋描述。

所有包含文檔化方法的對象

如果一個對象包含一個或多個附帶文檔注釋的方法，那麼這個對象也應當适當地針對文檔生成工具添加文檔注釋。

當然，注釋的詳細格式和用法最終還是由你所選擇的文檔生成工具決定的。