Generar documentación

Como vimos en el artículo anterior, JSDoc nos proporciona de serie muchas características super útiles en tiempo de desarrollo, es decir, sin instalar ni configurar ningún sistema especial, simplemente escribiendo comentarios de cierta forma, siguiendo unas pautas.

No obstante, podemos instalar JSDoc en nuestro proyecto y utilizar para generar una página con documentación de forma automática, que extrae de los comentarios del código.

Instalación de JSDoc

Para ello, lo único que tenemos que hacer es instalar JSDoc en nuestro proyecto:

$ npm install -D jsdoc

Una vez instalada esta dependencia de desarrollo, lo único que tenemos que hacer es ejecutar el comando jsdoc mediante npx, pnpm dlx para generar la documentación, pasándole el archivo principal:

$ npx jsdoc index.js

Esto generará una carpeta out/ con todos los archivos de la web de documentación (HTML, CSS, JS, etc...). Si queremos cambiar el nombre de la carpeta, bastará con añadir el parámetro -d nombre, donde nombre es la carpeta a generar.

Usando plantillas o temas

JSDoc utiliza la plantilla default de base, sin embargo, tiene la posibilidad de permitir utilizar otras plantillas para conseguir documentaciones más vistosas o bonitas.

Por ejemplo, indico algunas alternativas interesantes:

No obstante, hay muchas más, solo tienes que darte una vuelta por npmjs.com buscando jsdoc template.

Una vez instalado el paquete del template, este se guarda en node_modules. A la hora de generar la documentación, como vimos antes, le añadiremos el parámetro --template con la ruta del paquete a utilizar. Por ejemplo:

$ npx jsdoc src/index.js --template node_modules/clean-jsdoc-theme/

Esto usará el template de clean-jsdoc-theme para generar la documentación, que se verá similar a esto:

Generando información en JSON

Uno de los templates incluidos en JSDoc se llama haruki. Se trata de un template especial que genera la documentación en formato JSON. Esto puede ser especialmente interesante si luego queremos utilizar esa documentación en una web o consumir ese JSON para otros fines.

Simplemente, a la hora de generar la documentación, indicamos el template y añadimos el parámetro -d console:

$ npx jsdoc index.js --template node_modules/jsdoc/templates/haruki -d console

Al ejecutar este comando, se nos muestra una salida en formato JSON como la siguiente:

{
  "functions": [
    {
      "name": "sum",
      "access": "",
      "virtual": false,
      "description": "Función que suma dos números.",
      "parameters": [
        {
          "name": "a",
          "type": "number",
          "description": "Primer número",
          "default": "",
          "optional": "",
          "nullable": ""
        },
        {
          "name": "b",
          "type": "number",
          "description": "Segundo número",
          "default": "",
          "optional": "",
          "nullable": ""
        }
      ],
      "examples": [],
      "returns": {
        "type": "number",
        "description": "La suma de los dos números"
      }
    }
  ]
}

Recuerda que la ruta del template la estoy indicando como si estuvieramos en el raíz del proyecto, accediendo directamente a node_modules. Esa ruta puede variar en tu caso.