Introducción a JSDoc

Incluir documentación en el código base tiene su propia amplia gama de beneficios, algunos de los cuales incluyen la facilidad de comprensión del código para los nuevos programadores y también para los programadores experimentados que desean revisar su código base anterior. Al documentar el código, debe resumirlo correctamente. en la comprensión de todo el código base de forma adecuada.

JSDoc: un generador de documentación API para JavaScript.

JSDoc es un generador de documentación para Javascript, es similar a JavaDoc o Python Docstrings. Debe incluir comentarios de documentación en su código y luego JSDoc generará un sitio web de documentación HTML con la ayuda de esos comentarios.

Pasos para instalar JSDoc 

Para instalar JSDoc globalmente, ejecute el siguiente comando

npm install -g jsdoc

Si necesita instalar JSDoc como una dependencia de desarrollo en su proyecto, ejecute este comando en su lugar

npm install -D jsdoc

Configuración de JSDoc

En la propiedad «scripts» de package.json, necesitaremos agregar el comando jsdoc para ejecutar JSDoc y generar documentación. Agregue el comando similar al que se proporciona a continuación en el archivo package.json

"scripts": {
    "jsdoc": "jsdoc -c jsdoc.json"
    ...
  }

Este comando tiene una etiqueta -c que indica que jsdoc se ejecutará con un archivo de configuración personalizado. Por lo tanto, creemos un archivo de configuración para JSDoc.

En la raíz del directorio de su proyecto, cree un archivo llamado «jsdoc.json» , agregue el siguiente código en ese archivo: 

{
  "plugins": ["plugins/markdown"],
  "recurseDepth": 10,
  "source": {
    "include": ["src"],
    "includePattern": ".js$",
    "excludePattern": "(node_modules/|docs)"
  },
  "templates": {
    "cleverLinks": true,
    "monospaceLinks": true
  },
  "opts": {
    "destination": "./jsdoc",
    "recurse": true,
    "readme": "./readme.md"
  }
}

Explicación:

• El complemento Markdown está habilitado que convierte el texto con formato Markdown a HTML
• El valor recurseDepth se establece en 10, lo que indica cuántos niveles de profundidad buscará archivos el jsdoc
• Para especificar entradas, hemos incluido «src» en la propiedad include , esto significa que jsdoc generará documentación para archivos dentro del directorio src
• Incluir patrones dona qué archivo seleccionar, aquí .js$ indica que incluirá archivos .js, .jsx y .jsdoc
• La carpeta Node_modules y docs está excluida
• Las plantillas determinan la apariencia de la documentación generada
• La sección de opciones incluye comandos JSDoc

Ejecutando JSDoc

Vamos a crear un archivo index.js en la carpeta src y declarar una variable en él para generar documentación 

/**
 * Site Name
 * @type {string}
 */
const siteName = "GeeksForGeeks";

Aquí hemos creado una string llamada «nombre del sitio». En los comentarios, tenemos una descripción simple de la variable y la etiqueta @type que indica el tipo de variable
. En VSCode después de escribir /** , IntelliSense sugerirá automáticamente un comentario JSDoc, presione ingrese y escriba el comentario como se muestra a continuación.

Ahora que nuestro código está listo con la documentación, ejecutemos jsdoc y creemos una documentación.

Paso a ejecutar: Para ejecutar jsdoc, abra la terminal y escriba el siguiente comando

npm run jsdoc

Este comando creará una carpeta » jsdoc » en la raíz del directorio de su proyecto y dentro de ella, se generará un archivo index.html, puede abrirlo en un navegador para ver nuestra documentación generada

Producción: 

Documentación HTML generada