Apps Script の JSDoc

Google スプレッドシートの UI のドキュメントとスクリプトレベルのアノテーション。

Google Apps Script では、JSDoc を使用してスクリプトのドキュメントと オートコンプリートを生成します。JSDoc は、コメントを使用して JavaScript コードを記述するための標準です。

Apps Script では、JSDoc は主に次の目的で使用されます。

  1. エディタでのオートコンプリート: 入力時にパラメータのヒントと関数 の説明を表示します。
  2. Google スプレッドシートのカスタム関数: スプレッドシートの数式ヘルパーに表示されるように、カスタム関数を記述します。
  3. スクリプトレベルのアノテーション: 特別なタグを使用して、承認など、スクリプト全体の 動作を制御します。

関数のドキュメント

関数のドキュメントを作成するには、関数宣言の直上に JSDoc コメントブロックを配置します。JSDoc コメントは /** で始まり、*/ で終わります。

/**
 * Multiplies an input value by 2.
 *
 * @param {number} input The value to multiply.
 * @return {number} The input multiplied by 2.
 */
function double(input) {
  return input * 2;
}

このように関数を記述すると、関数を参照したときに Apps Script エディタにドキュメントのツールチップが表示されます。たとえば、エディタで「double(」と入力すると、次のように表示されます。

double(input)

入力値に 2 を掛けます。

input: number - 乗算する値。

一般的なタグ

タグ 説明
@param {type} name description 関数のパラメータを記述します。{type} と description は、開発環境で オートコンプリートに使用されます。
@return {type} description 関数の戻り値を記述します。
@example 関数の使用方法の例を示します。

オーバーロードと複数の型

JavaScript は従来の関数のオーバーロード（同じ名前の複数の関数を定義する）をサポートしていませんが、さまざまな種類の入力を処理する単一の関数を作成できます。これらの「オーバーロード」動作は JSDoc で記述できます。

ユニオン型

パラメータまたは戻り値が複数の型のいずれかになる可能性がある場合は、パイプ（|）を使用してユニオン型を作成します。これは、単一の値または値の範囲（2 次元配列として表される）を受け入れることができる関数で Apps Script でよく使用されます。

/**
 * Multiplies an input value (or a range of values) by 2.
 *
 * @param {number|number[][]} input The value or 2D array to multiply.
 * @return {number|number[][]} The result.
 */
function double(input) {
  return Array.isArray(input) ?
      input.map(row => row.map(cell => cell * 2)) :
      input * 2;
}

@overload を使用した複数のシグネチャ

許可されるパラメータが相互に依存する複雑なシグネチャを持つ関数では、@overload タグを使用して個別のシグネチャを定義できます。Apps Script エディタは、これらのタグを使用して、呼び出す関数のバージョンに基づいて具体的なヒントを提供します。

/**
 * @overload
 * @param {string} name The name of the property to get.
 * @return {string} The property value.
 */
/**
 * @overload
 * @param {number} index The index of the item to get.
 * @return {object} The item object.
 */
function get(arg) {
  // Implementation that handles both cases
}

Google スプレッドシートのカスタム関数

Google スプレッドシートのカスタム関数を作成する場合は、スプレッドシートのオートコンプリートと数式ヘルパーに表示されるように、@customfunction タグを使用する必要があります。

JSDoc は、ユーザーが Google スプレッドシートでカスタム関数を使用するときに表示されるヘルパー テキストのソースです。JSDoc がないと、ユーザーには関数名しか表示されないため、関数の機能や必要なパラメータを把握することが難しくなります。

サポートされているタグと UI の制限事項

Apps Script はほとんどの標準 JSDoc タグを解析しますが、カスタム関数の Google スプレッドシート UI には、次のような特定の動作と制限があります。

  • @customfunction: 関数をスプレッドシートの数式リストに表示するために必要です。
  • @param: 名前と説明はスプレッドシートの数式ヘルパーに表示されます。
  • @return: @return タグで指定された説明は、スプレッドシートの数式ヘルパーに表示されません 。
  • 省略可能なパラメータ: 省略可能なパラメータの標準 JSDoc 構文 （[name] や name= など）は、スプレッドシート UI で認識されません。すべてのパラメータが数式ヘルパーで必須として表示されます。
  • デフォルト値: デフォルトのパラメータ値（[name=Value] など）は、スプレッドシート UI で サポートされていません。
  • 書式設定: 説明の HTML タグとプレーン テキストの改行は サポートされていません。スプレッドシート UI では、説明が 1 つのテキストブロックとして表示され、ほとんどの HTML が削除されます。

Google スプレッドシートの例

/**
 * Calculates a discount.
 *
 * @param {number} price The original price.
 * @param {number} percent The discount percentage (e.g., 0.1 for 10%).
 * @return {number} The price after discount.
 * @customfunction
 */
function calculateDiscount(price, percent) {
  return price * (1 - percent);
}

Google スプレッドシートに表示される内容

ユーザーがセルに「=CALCULATEDISCOUNT(」と入力すると、Google スプレッドシートに次のヘルパー ボックスが表示されます。

CALCULATEDISCOUNT

割引を計算します。

price: 元の価格。

percent: 割引率（10% の場合は 0.1 など）。

パラメータの説明は、JSDoc の @param タグから直接取得されます。

スクリプトレベルのアノテーション

Apps Script は、独自の JSDoc タグを使用してスクリプト全体の設定を制御します。通常、これらはスクリプト ファイルの先頭に配置されます。

承認タグ

タグ 説明
@OnlyCurrentDoc Apps Script に、そのタイプのすべてのファイルではなく、現在のドキュメントの承認のみをリクエストするように指示します。詳細については、 [承認ガイド](/apps-script/guides/services/authorization)をご覧ください。
@NotOnlyCurrentDoc ライブラリで、継承された @OnlyCurrentDoc アノテーションをオーバーライドするために使用されます。