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 - 乗算する値。

共通のタグ

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

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 では認識されません。すべてのパラメータが数式ヘルパーで必須として表示されます。
• デフォルト値: シートの UI では、デフォルトのパラメータ値（[name=Value] など）はサポートされていません。
• 書式設定: 説明では、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 タグを使用します。通常、これらはスクリプト ファイルの先頭に配置されます。

承認タグ