@use JSDoc

關於 JSDoc 外掛程式

建立並啟用外掛程式

建立並啟用新的 JSDoc 外掛程式需要兩個步驟

  1. 建立一個 JavaScript 模組來包含外掛程式程式碼。
  2. 在 JSDoc 設定檔 的 plugins 陣列中包含該模組。您可以指定絕對或相對路徑。如果您使用相對路徑，JSDoc 會依序在目前的工作目錄、設定檔所在目錄和 JSDoc 目錄中搜尋外掛程式。

例如，如果您的外掛程式定義在目前工作目錄的 plugins/shout.js 檔案中，您會將字串 plugins/shout 新增到 JSDoc 設定檔中的 plugins 陣列

將外掛程式新增到 JSDoc 設定檔
{
    "plugins": ["plugins/shout"]
}

JSDoc 會依據設定檔中列出的順序執行外掛程式。

撰寫 JSDoc 3 外掛程式

JSDoc 3 的外掛程式系統提供對剖析過程的廣泛控制。外掛程式可透過執行下列任一動作來影響剖析結果

事件處理常式

在最高層級，外掛程式可能會為 JSDoc 觸發的特定命名事件註冊處理常式。JSDoc 會將事件物件傳遞給處理常式。您的外掛程式模組應該匯出包含處理常式的 handlers 物件，如下所示

'newDoclet' 事件的事件處理常式外掛程式
exports.handlers = {
    newDoclet: function(e) {
        // Do something when we see a new doclet
    }
};

JSDoc 會依據基礎程式碼的順序觸發事件。

事件處理常式外掛程式可以透過在事件物件上設定 stopPropagation 屬性 (e.stopPropagation = true) 來停止後續外掛程式執行。外掛程式可以透過設定 preventDefault 屬性 (e.preventDefault = true) 來停止事件觸發。

事件：parseBegin

parseBegin 事件會在 JSDoc 開始載入和剖析原始檔之前觸發。您的外掛程式可以透過修改事件的內容來控制 JSDoc 將剖析哪些檔案。

注意：此事件會在 JSDoc 3.2 及後續版本中觸發。

事件物件包含下列屬性

事件：fileBegin

當剖析器準備剖析檔案時，會觸發 fileBegin 事件。您的外掛程式可以使用此事件在必要時觸發每個檔案的初始化。

事件物件包含下列屬性

事件：beforeParse

beforeParse 事件在開始剖析前觸發。外掛程式可以使用此方法來修改將剖析的原始程式碼。例如，您的外掛程式可以新增 JSDoc 註解，或移除不是有效 JavaScript 的預處理標籤。

事件物件包含下列屬性

以下是一個範例，會為原始碼中的函式新增一個虛擬註解，以便剖析並新增到文件。這可以用於記錄對使用者可用的方法，但可能不會出現在正在記錄的原始碼中，例如外部超類別提供的方法

範例
exports.handlers = {
    beforeParse: function(e) {
        var extraDoc = [
            '/**',
            ' * Function provided by a superclass.',
            ' * @name superFunc',
            ' * @memberof ui.mywidget',
            ' * @function',
            ' */'
        ];
        e.source += extraDoc.join('\n');
    }
};

事件：jsdocCommentFound

jsdocCommentFound 事件在找到 JSDoc 註解時觸發。此註解可能與程式碼相關，也可能不相關。您可以在處理註解之前使用此事件來修改註解內容。

事件物件包含下列屬性

事件：symbolFound

當剖析器在程式碼中遇到可能需要記錄的符號時，會觸發 symbolFound 事件。例如，剖析器會為原始檔中的每個變數、函式和物件文字觸發 symbolFound 事件。

事件物件包含下列屬性

事件：newDoclet

newDoclet 事件是最高層級的事件。當建立新的文件時，此事件會觸發。這表示已處理 JSDoc 註解或符號，而且已建立將傳遞至範本的實際文件。

事件物件包含下列屬性

文件的屬性會根據文件所代表的註解或符號而有所不同。您可能會看到的一些常見屬性包括

若要查看 JSDoc 為您的程式碼產生的文件，請使用 -X 命令列選項 執行 JSDoc。

以下是會呼喊描述的 newDoclet 處理常式的範例

範例
exports.handlers = {
    newDoclet: function(e) {
        // e.doclet will refer to the newly created doclet
        // you can read and modify properties of that doclet if you wish
        if (typeof e.doclet.description === 'string') {
            e.doclet.description = e.doclet.description.toUpperCase();
        }
    }
};

事件：fileComplete

當解析器完成解析檔案時，會觸發 fileComplete 事件。您的外掛程式可以使用此事件觸發每個檔案的清除作業。

事件物件包含下列屬性

事件：parseComplete

當 JSDoc 解析完所有指定的原始檔後，會觸發 parseComplete 事件。

注意：此事件會在 JSDoc 3.2 及後續版本中觸發。

事件物件包含下列屬性

事件：processingComplete

processingComplete 事件會在 JSDoc 更新剖析結果以反映繼承和借用符號後觸發。

注意：此事件會在 JSDoc 3.2.1 及後續版本中觸發。

事件物件包含下列屬性

標籤定義

將標籤新增至標籤字典是影響文件產生中階的方式。在觸發 newDoclet 事件之前，會剖析 JSDoc 註解區塊以確定說明和可能存在的任何 JSDoc 標籤。當找到標籤時，如果已在標籤字典中定義，則會讓它修改 doclet。

外掛程式可以透過匯出 defineTags 函數來定義標籤。該函數會傳遞一個可用於定義標籤的字典，如下所示

範例
exports.defineTags = function(dictionary) {
    // define tags here
};

字典

字典提供下列方法

標籤的 onTagged 回呼可以修改文件說明或標籤的內容。

定義 onTagged 回呼
dictionary.defineTag('instance', {
    onTagged: function(doclet, tag) {
        doclet.scope = "instance";
    }
});

defineTag 方法會傳回一個 Tag 物件，其中有一個 synonym 方法，可用於宣告標籤的同義詞。

定義標籤同義詞
dictionary.defineTag('exception', { /* options for exception tag */ })
    .synonym('throws');

節點訪客

在最低層級，外掛程式作者可以透過定義節點訪客來處理抽象語法樹 (AST) 中的每個節點，該節點訪客會拜訪每個節點。透過使用節點訪客外掛程式，您可以修改註解，並觸發任何任意程式碼區段的剖析器事件。

外掛程式可以透過匯出包含 visitNode 函式的 astNodeVisitor 物件來定義節點訪客，如下所示

範例
exports.astNodeVisitor = {
    visitNode: function(node, e, parser, currentSourceName) {
        // do all sorts of crazy things here
    }
};

函式會呼叫每個節點，並帶有以下參數

讓事情發生

實作節點訪客的主要原因是能夠記錄通常不會記錄的事物（例如建立類別的函式呼叫），或自動產生未記錄程式碼的文件說明。例如，外掛程式可能會尋找對 _trigger 方法的呼叫，因為它知道這表示觸發事件，然後產生事件的文件說明。

為了讓事情發生，visitNode 函式應該修改事件參數的屬性。一般來說，目標是建立註解，然後讓事件觸發。剖析器讓所有節點訪客查看節點後，它會查看事件物件是否有 comment 屬性和 event 屬性。如果它同時具有這兩個屬性，則會觸發事件屬性中指定的事件。事件通常是 symbolFound 或 jsdocCommentFound，但理論上外掛程式可以定義自己的事件並處理它們。

與事件處理器外掛程式一樣，節點訪客外掛程式可以透過在事件物件上設定 stopPropagation 屬性 (e.stopPropagation = true) 來停止後續外掛程式的執行。外掛程式可以透過設定 preventDefault 屬性 (e.preventDefault = true) 來停止事件觸發。

回報錯誤

如果您的外掛程式需要回報錯誤，請使用 jsdoc/util/logger 模組中的下列方法之一

使用這些方法可以創造比單純拋出錯誤更好的使用者體驗。

注意：不要使用 jsdoc/util/error 模組來回報錯誤。此模組已過時，並將在 JSDoc 的未來版本中移除。

回報非致命錯誤
var logger = require('jsdoc/util/logger');

exports.handlers = {
    newDoclet: function(e) {
        // Your code here.

        if (somethingBadHappened) {
            logger.error('Oh, no, something bad happened!');
        }
    }
};