JSDoc in Apps Script

Dokumentation in der Google Sheets-Benutzeroberfläche und Anmerkungen auf Skriptebene.

Google Apps Script verwendet JSDoc, um Dokumentation und Autovervollständigung für Ihre Skripts zu generieren. JSDoc ist ein Standard zum Dokumentieren von JavaScript-Code mit Kommentaren.

In Apps Script dient JSDoc hauptsächlich folgenden Zwecken:

1. Autovervollständigung im Editor: Bereitstellen von Parameterhinweisen und Funktions beschreibungen während der Eingabe.
2. Benutzerdefinierte Funktionen in Google Sheets: Dokumentieren Ihrer benutzerdefinierten Funktionen, damit sie in der Formelhilfe von Google Sheets angezeigt werden.
3. Anmerkungen auf Skriptebene: Verwenden spezieller Tags, um das skriptweite Verhalten zu steuern, z. B. die Autorisierung.

Funktionen dokumentieren

Wenn Sie eine Funktion dokumentieren möchten, platzieren Sie einen JSDoc-Kommentarblock direkt über der Funktionsdeklaration. Ein JSDoc-Kommentar beginnt mit /** und endet mit */.

/**
 * 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;
}

Wenn Sie eine Funktion auf diese Weise dokumentieren, wird im Apps Script-Editor ein Dokumentationstooltip angezeigt, wenn Sie auf die Funktion verweisen. Wenn Sie beispielsweise double( in den Editor eingeben, sehen Sie Folgendes:

double(input)

Multipliziert einen Eingabewert mit 2.

input: number – Der zu multiplizierende Wert.

Häufig verwendete Tags

Überladungen und mehrere Typen

JavaScript unterstützt zwar keine klassische Funktionsüberladung (Definieren mehrerer Funktionen mit demselben Namen), Sie können aber eine einzelne Funktion schreiben, die verschiedene Eingabetypen verarbeitet. Sie können diese „überladenen“ Verhaltensweisen in JSDoc dokumentieren.

Union-Typen

Wenn ein Parameter oder Rückgabewert einen von mehreren Typen haben kann, verwenden Sie ein Pipe-Zeichen (|), um einen Union-Typ zu erstellen. Dies ist in Apps Script häufig bei Funktionen der Fall, die entweder einen einzelnen Wert oder einen Wertebereich (als 2D-Array dargestellt) akzeptieren können.

/**
 * 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;
}

Mehrere Signaturen mit @overload

Bei Funktionen mit komplexen Signaturen, bei denen die zulässigen Parameter voneinander abhängen, können Sie mit dem Tag @overload jede einzelne Signatur definieren. Der Apps Script-Editor verwendet diese, um spezifische Hinweise zu geben, je nachdem, welche Version der Funktion Sie aufrufen.

/**
 * @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
}

Benutzerdefinierte Funktionen in Google Sheets

Wenn Sie eine benutzerdefinierte Funktion für Google Sheets schreiben, müssen Sie das @customfunction Tag verwenden, damit sie in der Autovervollständigung und Formelhilfe des Tabellenblatts angezeigt wird.

JSDoc ist die Quelle für den Hilfetext, der Nutzern angezeigt wird, wenn sie Ihre benutzerdefinierte Funktion in Google Sheets verwenden. Ohne JSDoc sehen Nutzer nur den Funktionsnamen, sodass sie nicht wissen, was die Funktion tut oder welche Parameter sie benötigt.

Unterstützte Tags und Einschränkungen der Benutzeroberfläche

Apps Script parst zwar die meisten Standard-JSDoc-Tags, die Google Sheets-Benutzeroberfläche für benutzerdefinierte Funktionen hat jedoch einige spezifische Verhaltensweisen und Einschränkungen:

• @customfunction: Erforderlich, damit die Funktion in der Formelliste von Google Sheets angezeigt wird.
• @param: Der Name und die Beschreibung werden in der Formelhilfe von Google Sheets angezeigt.
• @return: Die im Tag @return angegebene Beschreibung wird nicht in der Formelhilfe von Google Sheets angezeigt.
• Optionale Parameter: Die Standard-JSDoc-Syntax für optionale Parameter (z.B. [name] oder name=) wird von der Google Sheets-Benutzeroberfläche nicht erkannt. Alle Parameter werden in der Formelhilfe als erforderlich angezeigt.
• Standardwerte: Standardparameterwerte (z.B. [name=Value]) werden in der Google Sheets-Benutzeroberfläche nicht unterstützt.
• Formatierung: HTML-Tags und Zeilenumbrüche im Nur-Text-Format in Ihrer Beschreibung werden nicht unterstützt. Die Google Sheets-Benutzeroberfläche zeigt die Beschreibung als einzelnen Textblock an und entfernt die meisten HTML-Elemente.

Beispiel für Google Sheets

/**
 * 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);
}

Was Nutzer in Google Sheets sehen

Wenn ein Nutzer =CALCULATEDISCOUNT( in eine Zelle eingibt, wird in Google Sheets das folgende Hilfefeld angezeigt:

CALCULATEDISCOUNT

Berechnet einen Rabatt.

price: Der ursprüngliche Preis.

Prozent: Der Rabatt in Prozent (z. B. 0,1 für 10%)

Die Beschreibungen für die Parameter stammen direkt aus Ihren JSDoc-Tags @param.

Anmerkungen auf Skriptebene

Apps Script verwendet eindeutige JSDoc-Tags, um skriptweite Einstellungen zu steuern. Diese werden in der Regel oben in einer Skriptdatei platziert.

Autorisierungs-Tags