如何使用 JSDoc 記錄 JavaScript 程式碼

正確的程式碼文件是軟體開發中重要但經常被忽視的方面。作為一名開發人員，您將習慣於編寫乾淨、高效的程式碼，但在編寫良好的文件方面您可能缺乏經驗。

對於所有參與涉及程式碼庫的協作工作的個人（包括您自己當前和未來的迭代）來說，有效的文件是寶貴的資源。透過澄清設計選擇並提供有關使用特定功能或 API 的指導，它可以促進使用者更好的理解和效率。

對於精通 JavaScript 程式設計的人來說，利用 JSDoc 是為其程式碼庫啟動文件流程的絕佳方法。

什麼是 JSDoc?

採用「文件即程式碼」策略已變得越來越流行，許多程式語言都提供了專用程式庫來簡化此過程。這些工具使開發人員能夠輕鬆產生全面而簡潔的文件。舉例來說，Go 程式語言提供 GoDoc，用於根據程式碼註釋自動生成文檔，而 JavaScript 在其生態系統中依賴 JSDoc 來實現類似目的。

JSDoc 利用 JavaScript 原始程式碼中嵌入的特殊註釋，有效地提取和處理此類註釋以產生客製化的文件。該文件隨後被格式化為用戶友好的 HTML 格式，以便於存取。

透過將文件直接整合到原始程式碼中，這種方法有助於在對程式碼進行修改時無縫更新程式碼及其對應文件。

設定 JSDoc

JSDoc 的設計者簡化了在 JavaScript 專案中啟動和整合 JSDoc 的過程，使其從一開始就易於存取且使用者友好。

若要在本機安裝 JSDoc，請執行:

 npm install --save-dev jsdoc

將程式庫作為專案中的開發依賴項安裝需要將其合併到專案的現有基礎架構中，使您能夠根據需要利用其特性和功能。

如何寫 JSDoc 註釋

要使用 JSDoc，必須將特定的註釋語法直接合併到其原始程式碼中。所有文件註解均由標籤/和 *//包圍，這允許詳細描述一系列廣泛的元素，例如定義的變數、函數、函數參數以及各種其他相關資訊。

例如:

 /**
 * Gets User by name.
 * @param {string} name - The name of the User
 * @returns {string} User
 */

function getUser(name) {
  const User = name;
  return User;
}

JSDoc 是一種 JavaScript 文件工具，它利用各種專用關鍵字（包括「@param」和「@returns」）來提供程式碼的清晰度。這些特定的關鍵字分別用作函數參數和傳回值的註釋，使開發人員能夠更好地理解他們的程式碼應該如何使用以及可以從中得到什麼結果。

若要建立概述此腳本功能的綜合文檔，請執行命令“npx jsdoc”，後面跟著指向 JavaScript 文件的指定路徑。

例如:

 npx jsdoc src/main.js

如果您已將 JSDoc 作為全域套件安裝，則只需執行以下命令即可放棄使用「npx」命令:

 jsdoc path/to/file.js 

執行此指令將導致在專案的主目錄中建立一個名為「out」的目錄。在該目錄中，您將發現包含文件內容的 HTML 文件。

為了存取文檔，您有兩種選擇。第一個涉及配置本機 Web 伺服器作為文檔文件的託管平台。或者，您可以選擇在您首選的 Web 瀏覽器中開啟 ut/index.html 檔案的內容，以直接檢視文件。請注意，文檔頁面的預設外觀如下:

配置 JSDoc 輸出

您可以選擇利用自訂設定檔來修改 JSDoc 的標準功能。

為了實現這個目標，需要建立一個名為「conf.js」的設定檔。在此文件中，應該導出一個 JavaScript 模組來實現其預期目的。

例如:

 module.exports = {
  source: {
    includePattern: ".\+\\\\.js(doc|x)?$",
    excludePattern: ["node_modules"],
  },
  recurseDepth: 5,
  sourceType: "module",
  opts: {
    template: "path/to/template",
    destination: "./docs/",
    recurse: true,
  },
};

設定檔內部有各種 JSDoc 設定 選項。範本選項可讓您使用範本來自訂文件的外觀。 JSDoc 社群提供了許多您可以使用的範本。該軟體包還允許您創建自己的個人化模板。

為了重新定位自動產生的文檔，必須透過調整標記為「目標」的配置設定來指定特定目錄作為目標。如前所述，指定位於專案主儲存區域內的指定「docs」資料夾將有效實現此目標。

執行以下指令以使用設定檔操作 JSDoc:

 jsdoc -c /path/to/conf.js

為了簡化執行此命令，請將其作為“scripts”條目包含在“package.json”文件中。這將允許透過執行「npm run [腳本名稱]」從專案目錄中的任何位置方便地執行命令。

 "scripts": {
    "dev": "nodemon app.js",
    "run-docs": "jsdoc -c /path/to/conf.js"
 },

現在可以在終端機環境中執行 npm script 命令，從而能夠執行與節點套件管理器關聯的預先定義腳本命令。

使用 JSDoc 產生文件的範例

下面是一個具有加法和減法方法的基本算術庫。

此範例示範了 JavaScript 的簡潔且結構良好的實現，其特點是其清晰的文件有助於理解和維護。

 /**
 * A library for performing basic arithmetic operations.
 * @module arithmetic
 */
module.exports = {
    /**
     * Adds two numbers.
     * @param {number} a - The first number.
     * @param {number} b - The second number.
     * @return {number} The sum of the two numbers.
     * @throws {TypeError} If any of the arguments is not a number.
     *
      * @example
     * const arithmetic = require('arithmetic');
     * const sum = arithmetic.add(5, 10);
     * console.log(sum); // 15
     */
    add: function(a, b) {
        if (typeof a !== 'number' || typeof b !== 'number') {
            throw new TypeError('Both arguments must be numbers.');
        }

        return a \+ b;
    },

    /**
     * Subtracts the second number from the first number.
     * @param {number} a - The number to subtract from.
     * @param {number} b - The number to subtract.
     * @return {number} The result of the subtraction.
     * @throws {TypeError} If any of the arguments is not a number.
     *
      * @example
     * const arithmetic = require('arithmetic');
     * const difference = arithmetic.subtract(10, 5);
     * console.log(difference); // 5
     */
    subtract: function(a, b) {
        if (typeof a !== 'number' || typeof b !== 'number') {
            throw new TypeError('Both arguments must be numbers.');
        }

        return a - b;
    }

    // ... other methods ...
};

JSDoc 註釋對庫及其功能進行了深入且全面的描述，其中包括:

該圖書館是各種文學作品的儲存庫，為顧客提供了大量的藏書，以滿足他們的智力追求。其主要目標是促進資訊和知識的獲取，使個人能夠透過閱讀和學習擴大視野。圖書館也透過保存歷史文獻和文學寶藏檔案，在保護文化遺產方面發揮著至關重要的作用。

每個單獨方法的輸入變量，包括它們的資料類型和簡潔的解釋。

每個函數產生的輸出的特徵、重要性或性質在其價值和分類方面可能有所不同。

為了更好地理解與給定方法相關的潛在問題，重要的是要考慮該方法可能引發的錯誤類型以及更可能發生這些錯誤的任何特定條件或環境。透過了解這些因素，開發人員可以採取措施降低風險並確保其程式碼在各種情況下都能順利運作。

提供的程式碼中的註解包含兩個重要的標籤，即“@module”標籤和“@example”標籤。前者表明該檔案是一個模組，而後者為每個相應的方法提供了說明性程式碼範例。對於尋求如何在自己的專案中有效利用這些方法的指導的開發人員來說，這些標籤可以作為有用的參考。

以正確的方式記錄開發人員程式碼

事實上，JSDoc 是一種透過無縫合併到開發過程中產生全面的 JavaScript 程式碼文件的有效方法。這有助於快速產生簡潔而複雜的文檔，同時實現專案環境中的持續更新和修訂。

雖然 JSDoc 提供的自動化功能對於產生文件可能非常有幫助，但仍必須遵守某些準則和最佳實踐，以確保建立高品質的文件。