@function (@func・@method)【関数・メソッド】
@param (@arg ・@argument )【引数】
@returns (@return)【戻り値】
@throws (@exception )【例外】
@generator【ジェネレータ関数】
@yields (@yield) 【ジェネレータ関数の戻り値】

@function【関数・メソッド】
@func【関数・メソッド】
@method【関数・メソッド】

メモ

構文

@function [関数・メソッド 名] 

シノニム：@func・@method

例

/** (@function 省略)
 * 関数を返却
 * @return 関数
 */
function getFunc() {
  /**
   * 内部関数
   * @global
   * @param {number} p1
   * @return {number} 二乗
   */
  function innerFunc(p1) {
    console.log(p1 * p1);
  }
  return innerFunc;
}

/**
 * 関数の説明
 * @function
 */
var func = getFunc();
func(2);              // 出力：4
func(3);              // 出力：9

@param【引数】
@arg【引数】
@argument【引数】

メモ

構文

@param [ {型} ] 引数名 [説明] 
シノニム：@arg・@argument

@param {型} 引数名 [説明]
  • JSDoc 3.2 以降：Google Closure Compiler の記述形式を全てサポート
  • 型：引数 (・戻り値・例外・型指定 等) の型
    型説明
    booleanBoolean型【真偽型】
    BooleanBoolean【真偽値】オブジェクト
    numberNumber型【数値型】
    NumberNumber【数値】オブジェクト
    stringString型【文字列型】
    StringString【文字列】オブジェクト
    nullnull【Null型】
    Objectオブジェクト
    標準組み込みオブジェクト名その他標準組み込みオブジェクト
    クラス名ユーザ定義クラス
    インタフェース名ユーザ定義インタフェース
    名前空間#メンバ名前空間のインスタンス メンバ
    名前空間.メンバ名前空間のスタティック メンバ
    名前空間~メンバ名前空間の内部 メンバ
    {型} の記述方法
    記述説明
    {型}通常
    {*}任意の型
    {?型} 型 または null
    {!型} null ではない型
    {型=} デフォルト値あり (値を明示的に指定する場合、引数名で指定)
    デフォルト引数 の値を自動識別
    {...型} 可変長引数 (arguments【引数リスト】 ・可変長引数 参照)
    {(型１|型２|  ～ |型ｎ)}
    {型１|型２|  ～ |型ｎ}     		複数の型
    {Array.<型>}
    {Array<型>}
    {型[ ]}     		配列
    {Object.<型１ , 型２>}
    {Object<型１ , 型２>}     		連想配列
    キー (型１) と 値 (型２) を持つ オブジェクト
    {{プロパティ名１[:型１],
     ～ プロパティ名ｎ[:型ｎ]}} オブジェクト名     		プロパティを持つオブジェクト
    プロパティの詳細出力なし
    未記述プロパティの参照は警告
    {Object} オブジェクト名
    以下はプロパティの詳細記述方法
    {型１} オブジェクト名.プロパティ名１
    ～
    {型ｎ} オブジェクト名.プロパティ名ｎ
    		プロパティを持つオブジェクト
    プロパティの詳細出力あり
  • 引数名：
    記述説明
    引数名省略不可
    [引数名]省略可能
    [引数名=デフォルト値] デフォルト値指定
    引数名.プロパティプロパティの説明
  • 説明：
    記述説明
    説明説明を記述
     - 説明可読性の為、説明の前に -(ハイフン) の指定可 (前後にスペース)

例

/**
 * 関数の説明
 * @param {number}        p1 引数１
 * @param {number|string} p2 引数２
 * @param {*}             p3 引数３
 * @return {boolean} 戻り値の説明
 *
 * @throws {Exception} 例外の説明
 */
function func(p1, p2) {
  var rc = false;
  /* 処理 */
  return rc;
}

【コードによるデフォルト引数】
/**
 * RGB値 取得
 * @param {number} [r=255] 赤色
 * @param {number} [g=255] 緑色
 * @param {number} [b=255] 青色
 * @return {number} RGB値
 */
function rgbA(r, g, b) {
  r = (r === undefined) ? 255 : r;
  g = (g === undefined) ? 255 : g;
  b = (b === undefined) ? 255 : b;
  return r * 0x10000 + g * 0x100 + b;
}

【デフォルト引数】
/**
 * RGB値 取得
 * @param {number=} r 赤色
 * @param {number=} g 緑色
 * @param {number=} b 青色
 * @return {number} RGB値
 */
function rgbB(r = 255, g = 255, b = 255) {
  return r * 0x10000 + g * 0x100 + b;
}

【引数をデフォルト引数に指定】
/**
 * 合計値 取得
 * @param {number} p1        パラメータ１
 * @param {number} [p2=p1+1] パラメータ２
 * @param {number} [p3=p2+1] パラメータ３
 * @return {number} 合計値
 */
function sumA(p1, p2 = p1 + 1, p3 = p2 + 1) {
  console.log("sumA：", p1, p2, p3);
  return p1 + p2 + p3;
}

【可変長引数 (arguments)】
/**
 * 合計値 取得
 * @param {...number} p1
 * @return {number} 合計値
 */
function sumB(p1) {
  var answer = 0;
  for (var i = 0; i < arguments.length; i++) {
    answer += arguments[i];
  }
  return answer;
}

【可変長引数】
/**
 * 合計値 取得
 * @param {number}    p1
 * @param {...number} pN
 * @return {number} 合計値
 */
function sumC(p1, ...pN) {
  var answer = p1;
  for (var i = 0; i < pN.length; i++) {
    answer += pN[i];
  }
  return answer;
}

【配列】
/**
 * 関数の説明
 * @param {Array.<number>} p1 引数１
 * @param {Array<number>}  p2 引数２
 * @param {number[]}       p3 引数３ 
 * @return {number}       合計値
 */
function sumArray(p1, p2, p3) {
  var sum = 0;
  for (var i = 0; i < p1.length; i++) {
    sum += p1[i];
  }
  for (var i = 0; i < p2.length; i++) {
    sum += p2[i];
  }
  for (var i = 0; i < p3.length; i++) {
    sum += p3[i];
  }
  return sum;
}

var array1 = [1, 2, 3];
var array2 = [4, 5, 6];
var array3 = [7, 8, 9];
var sum = sumArray(array1, array2, array3);
alert("sum：" + sum);

【連想配列】
/**
 * 関数の説明
 * @param {Object.<string, number>} obj1 引数１
 * @param {Object<string, number>}  obj2 引数２
 * @return {number} 合計値
 */
function funcObj1(obj1, obj2) {
  var sum = 0;
  for (var key in obj1) {
    sum += obj1[key];
    console.log("obj1." + key + " = " + obj1[key]);
  }
  for (var key in obj2) {
    sum += obj2[key];
    console.log("obj2." + key + " = " + obj2[key]);
  }
  return sum;
}

var obj11 = { keyA:1, keyB:2, keyC:3 };
var obj12 = { keyX:10, keyY:20, keyZ:30 };
var sum = funcObj1(obj11, obj12);
alert("sum：" + sum);


/**
 * 関数の説明
 * @param {{mem1: string, mem2: string}} obj オブジェクト (プロパティ mem1・プロパティ mem2)
 * @return {string} 結合文字列
 */
function funcObj2(obj) {
  var str = obj.mem1 + "-" + obj.mem2;
  return str;
}

var obj2 = { mem1:"STRING_A", mem2:"STRING_B" };
var str2 = funcObj2(obj2);
alert(str2);

/**
 * 関数の説明
 * @param {Object} obj      オブジェクト
 * @param {string} obj.mem1 オブジェクトのプロパティ mem1 
 * @param {string} obj.mem2 オブジェクトのプロパティ mem2 
 * @return {string} 結合文字列
 */
function funcObj3(obj) {
  var str = obj.mem1 + "-" + obj.mem2;
  return str;
}

var obj3 = { mem1:"STRING_X", mem2:"STRING_Y" };
var str3 = funcObj3(obj3);
alert(str3);

@return【戻り値】
@returns 【戻り値】

メモ

構文

@returns [{型}] [戻り値の説明] (１つは必要)

シノニム：@return

@return {型} [戻り値の説明]

例

/**
 * 関数の説明
 * @param {number} p1 引数１
 * @param {number} p2 引数２
 * @returns {boolean} 戻り値の説明
 *
 * @throws {Exception} 例外の説明
 */
function func(p1, p2) {
  var rc = false;
  /* 処理 */
  return rc;
}

@throws【例外】
@exception【例外】

メモ

構文

@throws [{型}] [例外の説明]  (１つは必要)

シノニム：@exception

@throws {型} [例外の説明]

例

/**
 * 関数の説明
 * @param {number} p1 引数１
 * @param {number} p2 引数２
 * @return {boolean} 戻り値の説明
 *
 * @throws {Exception} 例外の説明
 */
function func(p1, p2) {
  var rc = false;
  /* 処理 */
  return rc;
}

@generator【ジェネレータ関数】

メモ

構文

@generator

例

/**
 * ジェネレータ関数Ａの説明 (@function・@generator 省略)
 * @yields {number} 戻り値の説明
 */
function* funcGeneratorA() {
  for (i = 0; i < 5; i++) {
    yield i * 3;  // 0 -> 3 -> 6 -> 9 -> 12
  }
}

function* funcGeneratorB() {
  yield 100;
  yield* funcGeneratorA();
  yield 200;
}
/**
 * ジェネレータ関数Ｂの説明
 * @generator
 * @function funcGeneratorB
 * @yields {number} 戻り値の説明
 */

@yields【ジェネレータ関数の戻り値】
@yield【ジェネレータ関数の戻り値】

メモ

構文

@yields  [{型}] [戻り値の説明]  (１つは必要)
シノニム：@yield

例

/**
 * ジェネレータ関数の説明 (@function・@generator 省略)
 * @yields {number} 戻り値の説明
 */
function* funcGenerator() {
  for (i = 0; i < 5; i++) {
    yield i * 3;  // 0 -> 3 -> 6 -> 9 -> 12
  }
}