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 la saisie semi-automatique 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 conseils sur les paramètres et des descriptions de fonctions lors de la saisie.
2. Fonctions personnalisées dans Google Sheets : documente vos fonctions personnalisées afin qu' elles apparaissent dans l'assistant de formule Sheets.
3. Annotations au niveau du script : utilise des balises spéciales pour contrôler le comportement à l'échelle du script, 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 :

double(input)

Multiplie une valeur d'entrée par 2.

input : nombre : valeur à multiplier.

Balises courantes

Surcharges et types multiples

Bien que JavaScript ne soit pas compatible avec 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 peut être de plusieurs types, utilisez une barre verticale (|) pour créer un type d'union. Ceci 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;
}

Plusieurs signatures avec @overload

Pour les fonctions avec des signatures complexes 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 conseils 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 rendrait difficile de savoir ce qu'elle fait ou quels paramètres elle nécessite.

Balises compatibles et limites de l'interface utilisateur

Bien qu'Apps Script analyse la plupart des balises 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'assistant de formule Sheets.
• @return: la description fournie dans la balise @return n'est pas affichée dans l'assistant de formule 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 Sheets. Tous les paramètres s'affichent comme obligatoires dans l'assistant de formule.
• Valeurs par défaut : les valeurs de paramètre par défaut (par exemple, [name=Value]) ne sont pas compatibles avec l'interface utilisateur Sheets.
• Mise en forme : les balises HTML et les sauts de ligne en texte brut dans votre description ne sont pas acceptés. L'interface utilisateur Sheets affiche la description sous forme de bloc de texte unique 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 les utilisateurs voient dans Google Sheets

Lorsqu'un utilisateur saisit =CALCULATEDISCOUNT( dans une cellule, Google Sheets affiche la boîte 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 balises 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