@use JSDoc

同義詞

概觀

@param 標籤提供函式參數的名稱、類型和說明。

@param 標籤需要您指定要記錄的參數名稱。您也可以包含參數的類型（以大括號括住）和參數的說明。

參數類型可以是內建的 JavaScript 類型，例如 string 或 Object，或指向程式碼中另一個符號的 JSDoc 名稱路徑。如果您已為該名稱路徑中的符號撰寫文件，JSDoc 會自動連結到該符號的文件。您也可以使用類型表達式來表示，例如，參數不可為空值或可以接受任何類型；請參閱 @type 標籤文件 以取得詳細資料。

如果您提供說明，可以在說明前插入連字號，讓 JSDoc 註解更易於閱讀。請務必在連字號前後包含空格。

範例

名稱、類型和說明

以下範例顯示如何在 @param 標籤中包含名稱、類型和說明。

僅名稱
/**
 * @param somebody
 */
function sayHello(somebody) {
    alert('Hello ' + somebody);
}
名稱和類型
/**
 * @param {string} somebody
 */
function sayHello(somebody) {
    alert('Hello ' + somebody);
}
名稱、類型和說明
/**
 * @param {string} somebody Somebody's name.
 */
function sayHello(somebody) {
    alert('Hello ' + somebody);
}

您可以在說明前加入連字號，讓它更易於閱讀。請務必在連字號前後包含空格。

名稱、類型和說明，說明前有連字號
/**
 * @param {string} somebody - Somebody's name.
 */
function sayHello(somebody) {
    alert('Hello ' + somebody);
}

具有屬性的參數

如果預期參數具有特定屬性，您可以透過提供其他 @param 標籤來記錄該屬性。例如，如果預期 employee 參數具有 name 和 department 屬性，您可以如下記錄：

記錄參數的屬性
/**
 * Assign the project to an employee.
 * @param {Object} employee - The employee who is responsible for the project.
 * @param {string} employee.name - The name of the employee.
 * @param {string} employee.department - The employee's department.
 */
Project.prototype.assign = function(employee) {
    // ...
};

如果參數在沒有明確名稱的情況下解構，您可以給物件一個適當的名稱並記錄其屬性。

記錄解構參數
/**
 * Assign the project to an employee.
 * @param {Object} employee - The employee who is responsible for the project.
 * @param {string} employee.name - The name of the employee.
 * @param {string} employee.department - The employee's department.
 */
Project.prototype.assign = function({ name, department }) {
    // ...
};

您也可以將此語法與 JSDoc 的陣列參數語法結合使用。例如，如果可以將多個員工分配給專案

記錄陣列中值的屬性
/**
 * Assign the project to a list of employees.
 * @param {Object[]} employees - The employees who are responsible for the project.
 * @param {string} employees[].name - The name of an employee.
 * @param {string} employees[].department - The employee's department.
 */
Project.prototype.assign = function(employees) {
    // ...
};

選用參數和預設值

以下範例顯示如何表示參數是選用的且具有預設值。

選用參數（使用 JSDoc 語法）
/**
 * @param {string} [somebody] - Somebody's name.
 */
function sayHello(somebody) {
    if (!somebody) {
        somebody = 'John Doe';
    }
    alert('Hello ' + somebody);
}
選用參數（使用 Google Closure Compiler 語法）
/**
 * @param {string=} somebody - Somebody's name.
 */
function sayHello(somebody) {
    if (!somebody) {
        somebody = 'John Doe';
    }
    alert('Hello ' + somebody);
}
選用參數和預設值
/**
 * @param {string} [somebody=John Doe] - Somebody's name.
 */
function sayHello(somebody) {
    if (!somebody) {
        somebody = 'John Doe';
    }
    alert('Hello ' + somebody);
}

多個類型和可重複參數

下列範例說明如何使用類型表達式來表示參數可以接受多種類型（或任何類型），以及參數可以提供多次。有關 JSDoc 支援的類型表達式詳細資料，請參閱@type 標籤文件。

允許一種類型或另一種類型（類型聯集）
/**
 * @param {(string|string[])} [somebody=John Doe] - Somebody's name, or an array of names.
 */
function sayHello(somebody) {
    if (!somebody) {
        somebody = 'John Doe';
    } else if (Array.isArray(somebody)) {
        somebody = somebody.join(', ');
    }
    alert('Hello ' + somebody);
}
允許任何類型
/**
 * @param {*} somebody - Whatever you want.
 */
function sayHello(somebody) {
    console.log('Hello ' + JSON.stringify(somebody));
}
允許重複參數
/**
 * Returns the sum of all numbers passed to the function.
 * @param {...number} num - A positive or negative number.
 */
function sum(num) {
    var i = 0, n = arguments.length, t = 0;
    for (; i < n; i++) {
        t += arguments[i];
    }
    return t;
}

回呼函式

如果參數接受回呼函式，您可以使用@callback 標籤來定義回呼類型，然後將回呼類型包含在 @param 標籤中。

接受回呼的參數
/**
 * This callback type is called `requestCallback` and is displayed as a global symbol.
 *
 * @callback requestCallback
 * @param {number} responseCode
 * @param {string} responseMessage
 */

/**
 * Does something asynchronously and executes the callback on completion.
 * @param {requestCallback} cb - The callback that handles the response.
 */
function doSomethingAsynchronously(cb) {
    // code
};