JSDoc en Apps Script

Documentación en la IU de Hojas de cálculo de Google y anotaciones a nivel de la secuencia de comandos

Google Apps Script usa JSDoc para generar documentación y autocompletar tus secuencias de comandos. JSDoc es un estándar para documentar código JavaScript con comentarios.

En Apps Script, JSDoc tiene los siguientes propósitos principales:

  1. Autocompletar en el editor: Proporciona sugerencias de parámetros y descripciones de funciones a medida que escribes.
  2. Funciones personalizadas en Hojas de cálculo de Google: Documenta tus funciones personalizadas para que aparezcan en el asistente de fórmulas de Hojas de cálculo.
  3. Anotaciones a nivel de la secuencia de comandos: Uso de etiquetas especiales para controlar el comportamiento de toda la secuencia de comandos, como la autorización

Funciones de documentos

Para documentar una función, coloca un bloque de comentarios JSDoc directamente sobre la declaración de la función. Un comentario de JSDoc comienza con /** y 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;
}

Cuando documentas una función de esta manera, el editor de Apps Script muestra una información sobre la herramienta de documentación cuando haces referencia a la función. Por ejemplo, cuando escribes double( en el editor, ves lo siguiente:

double(input)

Multiplica un valor de entrada por 2.

input: número: Es el valor que se multiplicará.

Etiquetas comunes

Etiqueta Descripción
@param {type} name description Documenta un parámetro de función. El entorno de desarrollo usa {type} y description para la función de autocompletar.
@return {type} description Documenta el valor que devuelve la función.
@example Proporciona un ejemplo de cómo usar la función.

Sobrecargas y varios tipos

Si bien JavaScript no admite la sobrecarga de funciones clásica (definir varias funciones con el mismo nombre), puedes escribir una sola función que controle diferentes tipos de entrada. Puedes documentar estos comportamientos “sobrecargados” en JSDoc.

Tipos de unión

Si un parámetro o un valor de devolución pueden ser de varios tipos, usa una barra vertical (|) para crear un tipo de unión. Esto es común en Apps Script para las funciones que pueden aceptar un solo valor o un rango de valores (representado como un array 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;
}

Varias firmas con @overload

Para las funciones con firmas complejas en las que los parámetros permitidos dependen entre sí, puedes usar la etiqueta @overload para definir cada firma distinta. El editor de Apps Script los usa para proporcionar sugerencias específicas según la versión de la función que llamas.

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

Funciones personalizadas en Hojas de cálculo de Google

Cuando escribes una función personalizada para Hojas de cálculo de Google, debes usar la etiqueta @customfunction para que aparezca en el autocompletado y el asistente de fórmulas de la hoja de cálculo.

JSDoc es la fuente del texto de ayuda que los usuarios ven cuando usan tu función personalizada en Hojas de cálculo de Google. Sin JSDoc, los usuarios solo verían el nombre de la función, lo que dificultaría saber qué hace la función o qué parámetros requiere.

Etiquetas admitidas y limitaciones de la IU

Si bien Apps Script analiza la mayoría de las etiquetas JSDoc estándar, la IU de Hojas de cálculo de Google para las funciones personalizadas tiene algunos comportamientos y limitaciones específicos:

  • @customfunction: Se requiere para que la función aparezca en la lista de fórmulas de Hojas de cálculo.
  • @param: El nombre y la descripción se muestran en el asistente de fórmulas de Hojas de cálculo.
  • @return: La descripción proporcionada en la etiqueta @return no se muestra en el asistente de fórmulas de Hojas de cálculo.
  • Parámetros opcionales: La IU de Hojas de cálculo no reconoce la sintaxis estándar de JSDoc para los parámetros opcionales (p.ej., [name] o name=). Todos los parámetros aparecerán como obligatorios en el asistente de fórmulas.
  • Valores predeterminados: Los valores predeterminados de los parámetros (p.ej., [name=Value]) no se admiten en la IU de Hojas de cálculo.
  • Formato: No se admiten las etiquetas HTML ni los saltos de línea de texto sin formato en la descripción. La IU de Hojas de cálculo muestra la descripción como un solo bloque de texto y quita la mayor parte del código HTML.

Ejemplo para Hojas de cálculo de 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);
}

Qué ven los usuarios en Hojas de cálculo de Google

Cuando un usuario escribe =CALCULATEDISCOUNT( en una celda, Hojas de cálculo de Google muestra el siguiente cuadro de ayuda:

CALCULATEDISCOUNT

Calcula un descuento.

price: Es el precio original.

percent: Es el porcentaje de descuento (p.ej., 0.1 para el 10%).

Ten en cuenta que las descripciones de los parámetros provienen directamente de las etiquetas @param de JSDoc.

Anotaciones a nivel de secuencia de comandos

Apps Script usa etiquetas JSDoc únicas para controlar la configuración de toda la secuencia de comandos. Por lo general, se colocan en la parte superior de un archivo de secuencia de comandos.

Etiquetas de autorización

Etiqueta Descripción
@OnlyCurrentDoc Indica a Apps Script que solo solicite autorización para el documento actual en lugar de para todos los archivos de ese tipo. Consulta la [guía de autorización](/apps-script/guides/services/authorization) para obtener más detalles.
@NotOnlyCurrentDoc Se usa en las bibliotecas para anular una anotación @OnlyCurrentDoc heredada.