同義語
argargument
概要
@paramタグは、関数の引数の名前、タイプ、および説明を提供します。
@paramタグを使用するには、ドキュメント化する引数名を指定する必要があります。また、中括弧で囲まれた引数のタイプと、引数の説明を含めることもできます。
引数のタイプは、stringやObjectなどの組み込みJavaScriptタイプにするか、コード内の別のシンボルへのJSDoc名パスにすることができます。その名パスにあるシンボルのドキュメントを書いている場合、JSDocはそのシンボルのドキュメントに自動的にリンクします。また、たとえば引数がnull可能ではないことや、任意のタイプを受け付けることができることを示すために型式を使用することもできます。詳細については、@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) {
// ...
};
省略可能なパラメータとデフォルト値
次の例は、パラメータが省略可能であり、デフォルト値を持つことを示す方法を示しています。
/**
* @param {string} [somebody] - Somebody's name.
*/
function sayHello(somebody) {
if (!somebody) {
somebody = 'John Doe';
}
alert('Hello ' + somebody);
}
/**
* @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
};