JSDoc in Apps Script

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

Google Apps Script utilizza JSDoc per generare documentazione e completamento automatico per i tuoi script. JSDoc è uno standard per documentare il codice JavaScript utilizzando i commenti.

In Apps Script, JSDoc ha i seguenti 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 nella guida alle formule di Fogli.
  3. Annotazioni a livello di script: utilizzo di tag speciali per controllare il comportamento a livello di script, ad esempio l'autorizzazione.

Funzioni dei documenti

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 Apps Script mostra un suggerimento della documentazione quando fai riferimento alla funzione. Ad esempio, quando digiti double( nell'editor, visualizzi:

double(input)

Moltiplica un valore di input per 2.

input: number (numero) - Il valore da moltiplicare.

Tag comuni

Tag Descrizione
@param {type} name description Documenta un parametro di funzione. {type} e description vengono utilizzati dall'ambiente di sviluppo per il completamento automatico.
@return {type} description Documenta il valore restituito dalla funzione.
@example Fornisce un esempio di come utilizzare la funzione.

Sovraccarichi e più tipi

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

Tipi di unione

Se un parametro o un valore restituito può essere di diversi tipi, utilizza una barra verticale (|) per creare un tipo unione. Questo è comune in Apps Script per le funzioni che possono accettare un singolo valore o un intervallo di valori (rappresentato come una matrice bidimensionale).

/**
 * 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 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 alle 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, rendendo difficile capire cosa fa o quali parametri richiede.

Tag supportati e limitazioni della UI

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

  • @customfunction: obbligatorio per visualizzare la funzione nell'elenco delle formule di Fogli.
  • @param: il nome e la descrizione vengono visualizzati nella guida alle formule di Fogli.
  • @return: La descrizione fornita nel tag @return non viene visualizzata nella guida alle formule di Fogli.
  • Parametri facoltativi: la sintassi JSDoc standard per i parametri facoltativi (ad es. [name] o name=) non è riconosciuta dall'interfaccia utente di Fogli. Tutti i parametri verranno visualizzati come obbligatori nell'helper per le formule.
  • Valori predefiniti: i valori predefiniti dei parametri (ad es. [name=Value]) non sono supportati nell'interfaccia utente di Fogli.
  • Formattazione: i tag HTML e le interruzioni di riga in testo normale nella descrizione non sono supportati. L'interfaccia utente di Fogli mostra la descrizione come un unico blocco di testo e rimuove la maggior parte del codice 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);
}

Che cosa vedono gli utenti in Fogli Google

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

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 JSDoc @param.

Annotazioni a livello di script

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

Tag di autorizzazione

Tag Descrizione
@OnlyCurrentDoc Indica ad Apps Script di richiedere l'autorizzazione solo per il documento corrente anziché per tutti i file di quel tipo. Per ulteriori dettagli, consulta la [Guida all'autorizzazione](/apps-script/guides/services/authorization).
@NotOnlyCurrentDoc Utilizzato nelle librerie per eseguire l'override di un'annotazione @OnlyCurrentDoc ereditata.