JSDoc dans Apps Script

documentation dans l'interface utilisateur de Google Sheets et annotations au niveau du script.

Google Apps Script utilise JSDoc pour générer la documentation et l'autocomplétion de vos scripts. JSDoc est une norme permettant de documenter le code JavaScript à l'aide de commentaires.

Dans Apps Script, JSDoc remplit les fonctions principales suivantes :

  1. Saisie semi-automatique dans l'éditeur : fournit des indications sur les paramètres et des descriptions de fonctions à mesure que vous saisissez du texte.
  2. Fonctions personnalisées dans Google Sheets : documenter vos fonctions personnalisées pour qu'elles apparaissent dans l'outil d'aide pour les formules Sheets.
  3. Annotations au niveau du script : utilisation de tags spéciaux pour contrôler le comportement du script dans son ensemble, comme l'autorisation.

Fonctions de document

Pour documenter une fonction, placez un bloc de commentaires JSDoc directement au-dessus de la déclaration de la fonction. Un commentaire JSDoc commence par /** et se termine par */.

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

Lorsque vous documentez une fonction de cette manière, l'éditeur Apps Script affiche une info-bulle de documentation lorsque vous faites référence à la fonction. Par exemple, lorsque vous saisissez double( dans l'éditeur, vous voyez ce qui suit :

double(input)

Multiplie une valeur d'entrée par 2.

input : nombre : valeur à multiplier.

Tags courants

Tag Description
@param {type} name description Documente un paramètre de fonction. {type} et description sont utilisés par l'environnement de développement pour l'autocomplétion.
@return {type} description Documente la valeur de retour de la fonction.
@example Fournit un exemple d'utilisation de la fonction.

Surcharges et types multiples

Bien que JavaScript ne prenne pas en charge la surcharge de fonction classique (définition de plusieurs fonctions portant le même nom), vous pouvez écrire une seule fonction qui gère différents types d'entrée. Vous pouvez documenter ces comportements "surchargés" dans JSDoc.

Types d'union

Si un paramètre ou une valeur renvoyée peuvent être de plusieurs types, utilisez une barre verticale (|) pour créer un type d'union. C'est courant dans Apps Script pour les fonctions qui peuvent accepter une seule valeur ou une plage de valeurs (représentée sous forme de tableau 2D).

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

Signatures multiples avec @overload

Pour les fonctions dont les signatures sont complexes et où les paramètres autorisés dépendent les uns des autres, vous pouvez utiliser la balise @overload pour définir chaque signature distincte. L'éditeur Apps Script les utilise pour fournir des indications spécifiques en fonction de la version de la fonction que vous appelez.

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

Fonctions personnalisées dans Google Sheets

Lorsque vous écrivez une fonction personnalisée pour Google Sheets, vous devez utiliser la balise @customfunction pour qu'elle apparaisse dans la saisie semi-automatique et l'assistant de formule de la feuille de calcul.

JSDoc est la source du texte d'aide que les utilisateurs voient lorsqu'ils utilisent votre fonction personnalisée dans Google Sheets. Sans JSDoc, les utilisateurs ne verraient que le nom de la fonction, ce qui leur permettrait difficilement de savoir ce qu'elle fait ou les paramètres qu'elle requiert.

Balises acceptées et limites de l'UI

Bien qu'Apps Script analyse la plupart des tags JSDoc standards, l'interface utilisateur Google Sheets pour les fonctions personnalisées présente certains comportements et limites spécifiques :

  • @customfunction : obligatoire pour que la fonction s'affiche dans la liste des formules Sheets.
  • @param : le nom et la description s'affichent dans l'outil d'aide pour les formules Sheets.
  • @return : la description fournie dans la balise @return n'est pas affichée dans l'outil d'aide pour les formules Sheets.
  • Paramètres facultatifs : la syntaxe JSDoc standard pour les paramètres facultatifs (par exemple, [name] ou name=) n'est pas reconnue par l'interface utilisateur de Sheets. Tous les paramètres s'affichent comme obligatoires dans l'outil d'aide pour les formules.
  • Valeurs par défaut : les valeurs de paramètre par défaut (par exemple, [name=Value]) ne sont pas prises en charge dans l'interface utilisateur de Sheets.
  • Mise en forme : les balises HTML et les retours à la ligne en texte brut ne sont pas acceptés dans votre description. L'interface utilisateur de Sheets affiche la description sous forme d'un seul bloc de texte et supprime la plupart du code HTML.

Exemple pour 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);
}

Ce que voient les utilisateurs dans Google Sheets

Lorsqu'un utilisateur saisit =CALCULATEDISCOUNT( dans une cellule, Google Sheets affiche la zone d'aide suivante :

CALCULATEDISCOUNT

Calcule une remise.

price : prix d'origine.

percent : pourcentage de remise (par exemple, 0,1 pour 10 %).

Notez que les descriptions des paramètres proviennent directement de vos balises JSDoc @param.

Annotations au niveau du script

Apps Script utilise des tags JSDoc uniques pour contrôler les paramètres à l'échelle du script. Elles sont généralement placées en haut d'un fichier de script.

Balises d'autorisation

Tag Description
@OnlyCurrentDoc Indique à Apps Script de ne demander l'autorisation que pour le document actuel, et non pour tous les fichiers de ce type. Pour en savoir plus, consultez le [guide d'autorisation](/apps-script/guides/services/authorization).
@NotOnlyCurrentDoc Utilisé dans les bibliothèques pour remplacer une annotation @OnlyCurrentDoc héritée.