@function (@func・@method)【関数・メソッド】
@param (@arg ・@argument )【引数】
@returns (@return)【戻り値】
@throws (@exception )【例外】

@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【引数リスト】可変長引数 参照)
    {(【型1】|【型2】|  ~ |【型n】)}
    {【型1】|【型2】|  ~ |【型n】}
    複数の型
    {Array.<【型】>}
    {Array<【型】>}
    {【型】[ ]}
    配列
    {Object.<【型1】 , 【型2】>}
    {Object<【型1】 , 【型2】>}
    連想配列
    キー (型1) と 値 (型2) を持つ オブジェクト
    {{【プロパティ名1】[:【型1】],
     ~ 【プロパティ名n】[:【型n】]}} 【オブジェクト名】
    プロパティを持つオブジェクト
    プロパティの詳細出力なし
    未記述プロパティの参照は警告
    {Object} 【オブジェクト名】
    以下はプロパティの詳細記述方法
    {[【型1】]} 【オブジェクト名】.【プロパティ名1】

    {[【型n】]} 【オブジェクト名】.【プロパティ名n】
    プロパティを持つオブジェクト
    プロパティの詳細出力あり
  • 【引数名】:
    記述説明
    【引数名】省略不可
    [【引数名】]省略可能
    [【引数名】=【デフォルト値】] デフォルト値指定
    【引数名】.【プロパティ】プロパティの説明
  • 【説明】:
    記述説明
    【説明】説明を記述
     - 【説明】可読性の為、【説明】の前に -(ハイフン) の指定可 (前後にスペース)

関連

/**
 * 関数の説明
 * @param {number}        p1 引数1
 * @param {number|string} p2 引数2
 * @param {*}             p3 引数3
 * @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        パラメータ1
 * @param {number} [p2=p1+1] パラメータ2
 * @param {number} [p3=p2+1] パラメータ3
 * @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 引数1
 * @param {Array<number>}  p2 引数2
 * @param {number[]}       p3 引数3 
 * @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 引数1
 * @param {Object<string, number>}  obj2 引数2
 * @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);

@returns (@return)【戻り値】

メモ

  • 関数・コールバック関数の戻り値を記述
  • 複数指定可
  • 戻り値の型が実装と違う場合、警告

構文

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

シノニム:@return

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

関連

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

@throws (@exception )【例外】

メモ

  • 例外を記述
  • 複数指定可

構文

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

シノニム:@exception

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

関連

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