@param - JsDoc Toolkitを使う！

トップページ > ドックコメントの書き方 > タグリファレンス >

@param

@paramタグには、関数（コンストラクタ、メソッド）のパラメータについての情報を記述します。

• http://code.google.com/p/jsdoc-toolkit/wiki/TagParam

別名

@argument ※この別名は非推奨です。

構文

@param {paramType} paramName paramDescription

• paramType -- 省略可：パラメータのデータ型
• paramName -- 必須：パラメータ名
• paramDescription -- 省略可：パラメータの説明

例

/**
 * @param userName The name of the user.
 */

function logIn(userName) {
    // ...
}

基本

JsDocToolkitは関数宣言をパースし自動的にパラメータ名を見つけるので、技術的には@paramタグの使用は必ずしも必須ではありません。しかし@paramタグが提供するデータ型情報や説明文はとても有用なものです。

最も基本的な@paramタグの記述は、単にパラメータ名を示すだけです。これはソースコード内の同名のパラメータにマッチするはずです。

/**
 * @param userName
 */

function logIn(userName) {
    // ...
}

データ型情報

データ型情報をドキュメントに出力するには、型名を { } で囲んで記述します。

/**
 * @param {String} userName
 */

function logIn(userName) {
    // ...
}

複数のデータ型が許されている場合は、それぞれを | で区切って記述します。

/**
 * @param {String|Number} product
 */

データ型の後ろに [] がある場合は、配列を表します。

/**
 * @param {String[]} aliases
 */

省略可能なパラメータ

パラメータ名を [ ] で囲んで記述した場合、そのパラメータが省略可能であることを表します。

/**
 * @param {String} userName The user name to use when logging in.
 * @param {String} [accessLevel] The user accessLevel is optional.
 */

function logIn(userName, accessLevel) {
    // ...
}

デフォルト値を持つパラメータ

デフォルト値を持つためには、パラメータは省略可能でなければなりません。そしてパラメータ名が[ ]で囲まれていれば、そのパラメータは省略可能です。
デフォルト値は、パラメータ名のすぐ後ろに = 記号を付け、その後に記述します。デフォルト値として書かれた文字列はそのままの形で出力されることに注意してください。（JavaScriptは評価されません）

/**
 * @param {String} userName The user name to use when logging in.
 * @param {String} [accessLevel="author"] The user accessLevel is optional.
 */

function logIn(userName, accessLevel) {
    // ...
}

プロパティを持つパラメータ

パラメータが特定のプロパティを持つ無名オブジェクトの場合、以下のようにそのオブジェクトを表すパラメータの後に@paramタグを続けて書くことで、プロパティの情報をドキュメントに出力することができます。

/**
 * @param userInfo Information about the user.
 * @param userInfo.name The name of the user.
 * @param userInfo.email The email of the user.
 */

function logIn(userInfo) {
    doLogIn(userInfo.name, userInfo.email);
}

関連項目

• インライン・ドックコメントを使ったパラメータ記法

---