JSDoc no Apps Script

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

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

No Apps Script, o JSDoc tem estes propósitos 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 Planilhas Google: documenta suas funções personalizadas para que elas apareçam no auxiliar de fórmulas do Planilhas.
  3. Anotações no nível do script: usa tags especiais para controlar o comportamento do script, como a autorização.

Funções de documento

Para documentar uma função, coloque um bloco de comentários do JSDoc diretamente acima da declaração de 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 description são usados pelo ambiente de desenvolvimento para 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 (definir 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" no 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 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;
}

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 Planilhas Google

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

O JSDoc é a origem do texto de ajuda que os usuários veem quando usam sua função personalizada no Planilhas Google. Sem o JSDoc, os usuários só veriam o nome da função, dificultando saber o que ela faz ou quais parâmetros exige.

Tags compatíveis e limitações da interface

Embora o Apps Script analise a maioria das tags JSDoc padrão, a interface do Planilhas Google 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 Planilhas.
  • @param: o nome e a descrição são mostrados no auxiliar de fórmulas do Planilhas.
  • @return: a descrição fornecida na tag @return não é mostrada no auxiliar de fórmulas do Planilhas.
  • Parâmetros opcionais: a sintaxe JSDoc padrão para parâmetros opcionais (por exemplo, [name] ou name=) não é reconhecida pela interface do Planilhas. Todos os parâmetros vão aparecer como obrigatórios no auxiliar de fórmulas.
  • Valores padrão: os valores de parâmetros padrão (por exemplo, [name=Value]) não são aceitos na interface do Planilhas.
  • Formatação: tags HTML e quebras de linha de texto simples na descrição não são indisponíveis. A interface do Planilhas mostra a descrição como um único bloco de texto e remove a maior parte do HTML.

Exemplo para o Planilhas 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);
}

O que os usuários veem no Planilhas Google

Quando um usuário digita =CALCULATEDISCOUNT( em uma célula, o Planilhas Google 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. Elas geralmente são colocadas na parte de cima de um arquivo de script.

Tags de autorização

Tag Descrição
@OnlyCurrentDoc Informa ao Apps Script para 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 herdada @OnlyCurrentDoc.