Incluir fórmulas en la documentación de TSDoc

Posiblemente la forma más sencilla para crear la documentación de una librería escrita en TypeScript es usar TSDoc. Un formato estándar para escribir los comentarios a partir del cual se puede extraer información. Así, simplemente escribiendo los comentarios de las funciones, clases y métodos se crea y actualiza la documentación del proyecto. En el caso de trabajar con funciones que incluyen fórmulas matemáticas puede ser interesante incluir en la documentación estas expresiones, pero eso es algo que no soporta el estándar. Una manera de solucionar esto y poder incluir fórmulas en la documentación de TSDoc es mediante el uso de un plugin de TSDoc.

Un plugin que integrar KaTeX para TSDoc

Afortunadamente existe un plugin para TSDoc que permite integrar fórmulas de LaTeX en la documentación de TypeScript. Este plugin se llama typedoc-plugin-katex y se puede instalar mediante npm ejecutado en la carpeta del proyecto comando

npm install typedoc-plugin-katex --save-dev

Obviamente, para poder usarlo es necesario tener instalado previamente typedoc.

Inclusión de funciones en la documentación de TSDOC

Ahora, para incluir unas fórmulas de LaTeX en la documentación solamente se debe escribir esta entre símbolo $ para que este aparezca en línea o $$ para que se muestre en una línea independiente. Así, si se desea incluir la expresión de la media en la documentación de la librería tslane (que se creó en un serie anterior en la que se explicaba como crear una librería en TypeScript) solamente se debe escribir:

/**
 * Mean the elements of an array: $$\mu = \frac{1}{n} \sum_{i=1}^n x_i$$ where $n$ is the number of elements and $x$ the values
 *
 * @param arr - the input array
 *
 * @returns The mean of all elements of the array
 */
export function mean(arr: number[]): number {
  return sum(arr) / arr.length;
}

Ejecutar en el terminal el comando

typedoc --out docs src

Para poder comprobar que la documentación ahora se muestra de la siguiente manera.

Creación de macros

Al ejecutar el comando typedoc con el ejemplo anterior suele aparecer en la terminal una serie de mensajes de advertencia ya que el intérprete no entiende correctamente el código LaTeX. Si es una función no suele ser un problema, pero si cuando hay varias. Una forma de evitar este problema, y reutilizar las expresiones, es la creación de macros en el archivo typedoc.json del proyecto. Para trabajar con KaTeX en el proyecto se pueden agregar las siguientes opciones al archivo.

{
  "katex": {
    "version": "0.11.1",
    "options": {
      "delimiters": [
        {"left": "$$", "right": "$$", "display": true},
        {"left": "$", "right": "$", "display": false}
      ],
      "macros": {
        "\\mean": "\\mu = \\frac{1}{n} \\sum_{i=1}^n x_i"
      }
    }
  }
}

Con lo que se indica la versión de KaTeX a usar, los delimitadores ($, $$) y los macros que se deseen (en este caso la expresión de la media). Nótese que, en este caso, al ser un archivo JSON, es necesario escapar todas las barras usando dos en lugar de una. Así se puede reemplazar la fórmula en la documentación por el macro y evitar de esta forma los mensajes de advertencia. De este modo la función puede quedar documentada tal como se muestra a continuación. Evitando de esta manera los mensajes de advertencia.

/**
 * Mean the elements of an array: $$\mean$$ where $n$ is the number of elements and $x$ the values
 *
 * @param arr - the input array
 *
 * @returns The mean of all elements of the array
 */
export function mean(arr: number[]): number {
  return sum(arr) / arr.length;
}

Conclusiones

En esta entrada se ha visto cómo incluir fórmulas en la documentación de TSDoc mediante el uso de un plugin. Lo que permite mejorar la documentación cuando se está trabajando con funciones matemáticas que se quieren explicar al usuario.

El código de esta entrada se ha agregado al proyecto tslane en la versión 1.3.0. Proyecto que se puede encontrar en la cuenta de GitHub de Analytics Lane.