JSDoc 3 入門

入門

JSDoc 3 是 JavaScript 的 API 文件產生器，類似於 Javadoc 或 phpDocumentor。您可以將文件註解直接新增到原始程式碼，就在程式碼本身旁邊。JSDoc 工具會掃描您的原始程式碼，並為您產生 HTML 文件網站。

將文件註解新增到您的程式碼

JSDoc 的目的是文件化您的 JavaScript 應用程式或函式庫的 API。假設您會想要文件化模組、命名空間、類別、方法、方法參數等項目。

JSDoc 註解通常應該置於要文件化的程式碼之前。每個註解都必須以 /** 順序開始，才能被 JSDoc 剖析器辨識。以 /*、/*** 或超過 3 個星號開頭的註解將會被忽略。這是一個功能，讓您可以禁止註解區塊的剖析。

最簡單的文件化就是描述

/** This is a description of the foo function. */
function foo() {
}

新增描述很簡單，只要在文件註解中輸入您想要的描述即可。

可以使用特殊的「JSDoc 標籤」提供更多資訊。例如，如果函式是類別的建構函式，您可以透過新增 @constructor 標籤來表示這一點。

使用 JSDoc 標籤來描述您的程式碼

/**
 * Represents a book.
 * @constructor
 */
function Book(title, author) {
}

可以使用更多標籤來新增更多資訊。請參閱首頁，以取得 JSDoc 3 辨識的標籤完整清單。

使用標籤新增更多資訊

/**
 * Represents a book.
 * @constructor
 * @param {string} title - The title of the book.
 * @param {string} author - The author of the book.
 */
function Book(title, author) {
}

產生網站

在您的程式碼加上註解後，您可以使用 JSDoc 3 工具從您的原始檔案產生 HTML 網站。

預設情況下，JSDoc 使用內建的「預設」範本來將文件轉換為 HTML。您可以編輯此範本以符合您的需求，或建立一個全新的範本（如果您喜歡的話）。

在命令列上執行文件產生器

jsdoc book.js

此命令會在目前的作業目錄中建立一個名為 out/ 的目錄。在該目錄中，您會找到產生的 HTML 頁面。