JSDoc in Apps Script

documentazione nell'interfaccia utente di Fogli Google e annotazioni a livello di script.

Google Apps Script utilizza JSDoc per generare la documentazione e il completamento automatico degli script. JSDoc è uno standard per la documentazione del codice JavaScript tramite commenti.

In Apps Script, JSDoc ha questi scopi principali:

1. Completamento automatico nell'editor: fornisce suggerimenti sui parametri e descrizioni delle funzioni durante la digitazione.
2. Funzioni personalizzate in Fogli Google: documenta le funzioni personalizzate in modo che vengano visualizzate nell'assistente per le formule di Fogli.
3. Annotazioni a livello di script: utilizza tag speciali per controllare il comportamento a livello di script, ad esempio l'autorizzazione.

Funzioni di documentazione

Per documentare una funzione, inserisci un blocco di commenti JSDoc direttamente sopra la dichiarazione della funzione. Un commento JSDoc inizia con /** e termina con */.

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

Quando documenti una funzione in questo modo, l'editor di Apps Script mostra un suggerimento di documentazione quando fai riferimento alla funzione. Ad esempio, quando digiti double( nell'editor, viene visualizzato:

double(input)

Moltiplica un valore di input per 2.

input: numero: il valore da moltiplicare.

Tag comuni

Overload e più tipi

Sebbene JavaScript non supporti l'overload delle funzioni classiche (definizione di più funzioni con lo stesso nome), puoi scrivere una singola funzione che gestisce diversi tipi di input. Puoi documentare questi comportamenti "overload" in JSDoc.

Tipi di unione

Se un parametro o un valore restituito può essere di uno dei diversi tipi, utilizza una barra verticale (|) per creare un tipo di unione. Questo è comune in Apps Script per le funzioni che possono accettare un singolo valore o un intervallo di valori (rappresentato come un array 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;
}

Più firme con @overload

Per le funzioni con firme complesse in cui i parametri consentiti dipendono l'uno dall'altro, puoi utilizzare il tag @overload per definire ogni firma distinta. L'editor di script di Apps Script li utilizza per fornire suggerimenti specifici in base alla versione della funzione che stai chiamando.

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

Funzioni personalizzate in Fogli Google

Quando scrivi una funzione personalizzata per Fogli Google, devi utilizzare il tag @customfunction affinché venga visualizzata nel completamento automatico e nell'assistente per le formule del foglio di lavoro.

JSDoc è l'origine del testo di assistenza che gli utenti vedono quando utilizzano la tua funzione personalizzata in Fogli Google. Senza JSDoc, gli utenti vedrebbero solo il nome della funzione, il che renderebbe difficile sapere cosa fa la funzione o quali parametri richiede.

Tag supportati e limitazioni dell'interfaccia utente

Sebbene Apps Script analizzi la maggior parte dei tag JSDoc standard, l'interfaccia utente di Fogli Google per le funzioni personalizzate presenta alcuni comportamenti e limitazioni specifici:

• @customfunction: è obbligatorio affinché la funzione venga visualizzata nell'elenco delle formule di Fogli.
• @param: il nome e la descrizione vengono visualizzati nell'assistente per le formule di Fogli.
• @return: la descrizione fornita nel tag @return non viene visualizzata nell'assistente per le formule di Fogli.
• Parametri facoltativi: la sintassi JSDoc standard per i parametri facoltativi (ad es. [name] o name=) non viene riconosciuta dall'interfaccia utente di Fogli. Tutti i parametri verranno visualizzati come obbligatori nell'assistente per le formule.
• Valori predefiniti: i valori dei parametri predefiniti (ad es. [name=Value]) non sono supportati nell'interfaccia utente di Fogli.
• Formattazione: i tag HTML e gli interruzioni di riga di testo normale nella descrizione non sono supportati. L'interfaccia utente di Fogli visualizza la descrizione come un singolo blocco di testo e rimuove la maggior parte dell'HTML.

Esempio per Fogli 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);
}

Cosa vedono gli utenti in Fogli Google

Quando un utente digita =CALCULATEDISCOUNT( in una cella, Fogli Google visualizza la seguente casella di assistenza:

CALCULATEDISCOUNT

Calcola uno sconto.

price: il prezzo originale.

percent: la percentuale di sconto (ad es. 0,1 per il 10%).

Tieni presente che le descrizioni dei parametri provengono direttamente dai tag @param di JSDoc.

Annotazioni a livello di script

Apps Script utilizza tag JSDoc univoci per controllare le impostazioni a livello di script. Questi vengono in genere inseriti nella parte superiore di un file di script.

Tag di autorizzazione