JSDoc no Apps Script

documentação na interface do Google Planilhas e anotações no nível do script.

O Google Apps Script usa o JSDoc para gerar documentação e preenchimento automático para seus scripts. O JSDoc é um padrão para documentar código JavaScript usando comentários.

No Apps Script, o JSDoc tem as seguintes finalidades principais:

  1. Preenchimento automático no editor: fornece dicas de parâmetros e descrições de funções enquanto você digita.
  2. Funções personalizadas no Google Planilhas: documente suas funções personalizadas para que elas apareçam no assistente de fórmulas do Planilhas.
  3. Anotações no nível do script: uso de tags especiais para controlar o comportamento em todo o script, como autorização.

Funções de documento

Para documentar uma função, coloque um bloco de comentários JSDoc diretamente acima da declaração da função. Um comentário do JSDoc começa com /** e termina com */.

/**
 * 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 você documenta uma função dessa forma, o editor de script do Apps Script mostra uma dica de documentação quando você faz referência à função. Por exemplo, quando você digita double( no editor, aparece:

double(input)

Multiplica um valor de entrada por 2.

input: número — o valor a ser multiplicado.

Tags comuns

Tag Descrição
@param {type} name description Documenta um parâmetro de função. O {type} e o description são usados pelo ambiente de desenvolvimento para o preenchimento automático.
@return {type} description Documenta o valor de retorno da função.
@example Fornece um exemplo de como usar a função.

Sobrecargas e vários tipos

Embora o JavaScript não ofereça suporte à sobrecarga de função clássica (definição de várias funções com o mesmo nome), é possível escrever uma única função que processe diferentes tipos de entrada. Você pode documentar esses comportamentos "sobrecarregados" em JSDoc.

Tipos de união

Se um parâmetro ou valor de retorno puder ser de vários tipos, use uma barra vertical (|) para criar um tipo de união. Isso é comum no Apps Script para funções que podem aceitar um único valor ou um intervalo de valores (representado como uma matriz bidimensional).

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

Várias assinaturas com @overload

Para funções com assinaturas complexas em que os parâmetros permitidos dependem uns dos outros, use a tag @overload para definir cada assinatura distinta. O editor de script do Apps Script usa essas informações para fornecer dicas específicas com base na versão da função que você está chamando.

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

Funções personalizadas no Google Planilhas

Ao escrever uma função personalizada para o Google Planilhas, use a tag @customfunction para que ela apareça no preenchimento automático e no assistente de fórmulas da planilha.

O JSDoc é a fonte do texto de ajuda que os usuários veem ao usar sua função personalizada no Google Planilhas. Sem o JSDoc, os usuários só veriam o nome da função, o que dificultaria saber o que ela faz ou quais parâmetros são necessários.

Tags compatíveis e limitações da interface

Embora o Apps Script analise a maioria das tags JSDoc padrão, a interface do usuário do Google Planilhas para funções personalizadas tem alguns comportamentos e limitações específicos:

  • @customfunction: obrigatório para que a função apareça na lista de fórmulas do Google Sheets.
  • @param: o nome e a descrição são mostrados no assistente de fórmulas do Planilhas.
  • @return: a descrição fornecida na tag @return não aparece no assistente de fórmulas do Google Planilhas.
  • Parâmetros opcionais: a sintaxe padrão do JSDoc para parâmetros opcionais (por exemplo, [name] ou name=) não é reconhecida pela interface do usuário do Google Sheets. Todos os parâmetros vão aparecer como obrigatórios no assistente de fórmula.
  • Valores padrão: os valores de parâmetro padrão (por exemplo, [name=Value]) não são compatíveis com a interface do usuário do Google Sheets.
  • Formatação: tags HTML e quebras de linha de texto simples na descrição não são compatíveis. A interface do usuário do app Planilhas mostra a descrição como um único bloco de texto e remove a maior parte do HTML.

Exemplo para o Google Planilhas

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

O que os usuários veem no Google Planilhas

Quando um usuário digita =CALCULATEDISCOUNT( em uma célula, o Google Planilhas mostra a seguinte caixa de ajuda:

CALCULATEDISCOUNT

Calcula um desconto.

price: o preço original.

percent: a porcentagem de desconto (por exemplo, 0,1 para 10%).

As descrições dos parâmetros vêm diretamente das tags @param do JSDoc.

Anotações no nível do script

O Apps Script usa tags JSDoc exclusivas para controlar as configurações de todo o script. Normalmente, eles são colocados na parte de cima de um arquivo de script.

Tags de autorização

Tag Descrição
@OnlyCurrentDoc Instrui o Apps Script a solicitar autorização apenas para o documento atual, em vez de todos os arquivos desse tipo. Consulte o [guia de autorização](/apps-script/guides/services/authorization) para mais detalhes.
@NotOnlyCurrentDoc Usado em bibliotecas para substituir uma anotação @OnlyCurrentDoc hereditária.