Documentación en JavaScript

Documentación en JavaScript#

En este capítulo, exploraremos cómo documentar correctamente tus funciones y clases utilizando comentarios y JSDoc, una herramienta popular para generar documentación automática.

Comentarios en JavaScript#

Los comentarios en JavaScript son textos especiales que no afectan la ejecución del programa, pero son útiles para documentar el código y hacerlo más comprensible. Hay varios estilos de comentarios, pero los más relevantes para la documentación son los comentarios de bloque con /** ... */, que son reconocidos por herramientas como JSDoc para generar documentación.

/**
 * Esta función calcula la suma de dos números.
 * @param {number} a - El primer número.
 * @param {number} b - El segundo número.
 * @returns {number} La suma de a y b.
 */
function sum(a, b) {
    return a + b;
}

En este ejemplo:

  • @param indica los parámetros que recibe la función y sus tipos.

  • @returns especifica el tipo de retorno de la función.

JSDoc#

JSDoc es una herramienta que convierte los comentarios especiales en código JavaScript en documentación legible automáticamente. Aquí están los pasos básicos para usar JSDoc:

  1. Instalación de JSDoc:

    Para instalar JSDoc globalmente, puedes ejecutar el siguiente comando:

    sudo npm install -g jsdoc

  2. Uso de JSDoc:

    Puedes generar la documentación ejecutando el comando jsdoc seguido del nombre del archivo o directorio que contiene tus funciones y clases documentadas.

    Por ejemplo, para documentar un archivo book.js, puedes usar:

    jsdoc book.js

  3. Estructura de los Comentarios JSDoc:

    Los comentarios JSDoc tienen una estructura específica que incluye etiquetas especiales para describir los parámetros, retornos, constructores, propiedades, etc. A continuación, un ejemplo detallado:

    /**
 * Representa un libro.
 * @constructor
 * @param {string} title - El título del libro.
 * @param {string} author - El autor del libro.
 */
function Book(title, author) {
    this.title = title;
    this.author = author;
}

/**
 * Obtiene el título del libro.
 * @returns {string} El título del libro.
 */
Book.prototype.getTitle = function() {
    return this.title;
};

    En este ejemplo:

    • @constructor indica que la función es un constructor de una clase.

    • @param describe los parámetros que recibe el constructor.

    • @returns especifica el tipo de retorno de la función.

Integración con Visual Studio Code#

Visual Studio Code tiene soporte integrado para JSDoc, lo que significa que cuando comienzas a escribir /** encima de una función o método, automáticamente te genera un esqueleto básico de comentarios JSDoc que puedes completar.

Documentación de un proyecto completo#

JSDoc es muy útil para documentar el código. si queremos documentar todo un proyecto, al margen del código o hacer el manual de usuario, por ejemplo, podemos recurrir a herramientas de generación de sitios estáticos a partir de MarkDown. Por ejemplo, este libro está hecho con Jupyter Notebook, pero hay otras muchas opciones como Docusaurus o Jekyll. Estos sitios estáticos se pueden subir a Github Pages, Vercel o cualquier servidor web y el resultado es muy parecido a cualquier manual que se pueda encontrar actualmente por Internet, como este libro, por ejemplo.

Contents