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 mithilfe von Kommentaren.

In Apps Script hat JSDoc die folgenden Hauptfunktionen:

  1. Automatische Vervollständigung im Editor: Während der Eingabe werden Parameterhinweise und Funktionsbeschreibungen angezeigt.
  2. Benutzerdefinierte Funktionen in Google Sheets: Dokumentieren Sie Ihre benutzerdefinierten Funktionen, damit sie in der Formelhilfe von Google Sheets angezeigt werden.
  3. Anmerkungen auf Skriptebene: Mit speziellen Tags können Sie das Verhalten des gesamten Skripts steuern, z. B. die Autorisierung.

Dokumentfunktionen

Um eine Funktion zu dokumentieren, 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 eine Dokumentationskurzinfo 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 Wert, der multipliziert werden soll.

Häufig verwendete Tags

Tag Beschreibung
@param {type} name description Dokumentiert einen Funktionsparameter. Die {type} und description werden von der Entwicklungsumgebung für die automatische Vervollständigung verwendet.
@return {type} description Dokumentiert den Rückgabewert der Funktion.
@example Enthält ein Beispiel für die Verwendung der Funktion.

Überladungen und mehrere Typen

JavaScript unterstützt keine klassische Funktionsüberladung (Definition mehrerer Funktionen mit demselben Namen). Sie können jedoch eine einzelne Funktion schreiben, die verschiedene Arten von Eingaben 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 einen senkrechten Strich (|), um einen Union-Typ zu erstellen. Das ist in Apps Script für Funktionen üblich, 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 basierend darauf zu geben, 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 Tabellen schreiben, müssen Sie das @customfunction-Tag verwenden, damit sie in der automatischen Vervollständigung und der Formelhilfe des Tabellenblatts angezeigt wird.

JSDoc ist die Quelle für den Hilfetext, der Nutzern angezeigt wird, wenn sie Ihre benutzerdefinierte Funktion in Google Tabellen verwenden. Ohne JSDoc würden Nutzer nur den Funktionsnamen sehen. Es wäre also schwierig zu erkennen, was die Funktion macht oder welche Parameter sie benötigt.

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

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

  • @customfunction: Erforderlich, damit die Funktion in der Formelliste von Google Tabellen angezeigt wird.
  • @param: Name und Beschreibung werden in der Formelhilfe von Google Tabellen angezeigt.
  • @return: Die im @return-Tag 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 Sheets-Benutzeroberfläche nicht erkannt. Alle Parameter werden in der Formelhilfe als erforderlich angezeigt.
  • Standardwerte: Standardparameterwerte (z.B. [name=Value]) werden in der Sheets-Benutzeroberfläche nicht unterstützt.
  • Formatierung: HTML-Tags und Zeilenumbrüche im Nur-Text-Format in Ihrer Beschreibung werden nicht unterstützt. In der Sheets-Benutzeroberfläche wird die Beschreibung als einzelner Textblock angezeigt und der Großteil des HTML-Codes wird entfernt.

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 sehen Nutzer in Google Sheets?

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

CALCULATEDISCOUNT

Berechnet einen Rabatt.

price: Der ursprüngliche Preis.

percent: Der Rabattprozentsatz (z. B. 0,1 für 10%).

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

Annotationen auf Skriptebene

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

Autorisierungs-Tags

Tag Beschreibung
@OnlyCurrentDoc Weist Apps Script an, die Autorisierung nur für das aktuelle Dokument und nicht für alle Dateien dieses Typs anzufordern. Weitere Informationen finden Sie im [Autorisierungsleitfaden](/apps-script/guides/services/authorization).
@NotOnlyCurrentDoc Wird in Bibliotheken verwendet, um eine geerbte @OnlyCurrentDoc-Annotation zu überschreiben.