Hacer la documentación de una API puede llegar a ser muy tedioso, todos los programadores prefieren ir directo al grano, escribir su código y pasar de largo esta aburrida tarea. Para la fortuna de todos, actualmente existen un montón de herramientas para agilizar la documentación del código sin tener que dedicarle más del tiempo necesario. JSDoc es una de esas herramientas, al funcionar para Javascript (un lenguaje popular en la actualidad) la vuelve un foco de atención.
¿Qué es JSDoc?
JSDoc es un generador de documentación para el lenguaje de Javascript, muy similar a phpDocumentor o Javadoc que funciona para Java. JSDoc analiza el código Javascript y automáticamente genera una página HTML con la documentación en ella.
Algunas personas denominan a JSDoc como un lenguaje de marcado, que puede ser fácilmente integrado con cualquier IDE utilizado para desarrollo.
Instalación de JSDoc
Para poder usar JSDoc, es necesario descargar e instalarlo. Esto puede hacerse de manera global por medio del manejador de paquetes de NodeJs (se asume que el usuario ha instalado previamente npm), con el siguiente comando:
|
1 |
npm install -g jsdoc |
En caso de que se requiera instalar de manera local (para su uso dentro de un proyecto específico) debe ser guardado en el archivo package.json con el siguiente comando:
|
1 |
npm install --save-dev jsdoc |
Etiquetas de JSDoc
La documentación generada por JSDoc se crea con base a comentarios dentro del código fuente. Estos deben colocarse inmediatamente antes del código a documentar. Cada comentario debe comenzar con / ** y terminar con */ para ser reconocido por el analizador JSDoc. Después de iniciar un comentario se agrega un * por cada línea antes del cierre de comentario. En estas líneas, es donde deben ser agregadas las etiquetas.
JSDoc cuenta con una gran variedad de etiquetas, que permiten personalizar la documentación. Estas etiquetas van desde simples parámetros de una función, hasta objetos muy complejos.
A continuación se listan las etiquetas más utilizadas de esta herramienta:
-
@class
Esta etiqueta define una función como un constructor, destinada a ser llamada con su nombre para devolver una instancia.
@class {tipo} {nombre} -
@description
Proporciona una descripción general del segmento de código que se está documentando.
@description Descripción del segmento -
@param
Especifica el nombre, el tipo y la descripción de un parámetro de una función o un método.
@param {tipo} Descripción del parámetro -
@property
Esta etiqueta provee una forma de documentar fácilmente una lista de propiedades estáticas de una clase, namespace u otro objeto.
@property {tipo} Nombre de la propiedad -
@returns
Documenta el valor de retorno de una función.
@returns {tipo} Descripción -
@type
Ofrece información acerca del tipo de valor que puede ser contenido en un objeto o variable, entre otros.
@type {tipo} -
@typedef
Esta etiqueta es útil para documentar tipos personalizados, especialmente si desea consultarlos repetidamente.
@typedef {tipo} Nombre
Ejemplo de uso de JSDoc
En el siguiente ejemplo podemos ver como se utiliza JSDoc para una clase Cilindro, que contiene una función para calcular su volumen.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
/** * @class La clase Cilindro crea nuevas instancias con un radio y altura determinada */ function Cilindro(){ /** * @type {number} */ this.volumen = 0; /** * @description Determina el volumen de un cilindro con la altura y radio especificado * @param {number} radio El radio de los círculos laterales del cilindro * @param {number} altura La altura del cilindro * @return {number} */ this.volumen = function obtenerVolumen(radio, altura) { const volumen = (Math.PI * Math.pow(radio, 2) * altura); return volumen; } } |
Generando la documentación de API con JSDoc
Una vez el código se encuentre correctamente comentado, ejecutamos la herramienta de JSDoc:
|
1 |
jsdoc archivo.js |
Hecho lo anterior se generan los archivos HTML de la documentación y son almacenados en automático en la ruta out/.
En la siguiente imagen se puede apreciar la pagina generada por JSDoc, que describe la clase Cilindro usada en el ejemplo, junto con su función para calcular el volumen.
Para más ejemplos e información detallada, se sugiere visitar la página oficial de JSDoc, en la cual se describe todo a detalle:
Referencias.
- JSDoc org. (s.f.). @use JSDoc. Recuperado el Octubre de 31 de 2017, de http://usejsdoc.org/
- Microsoft. (Julio de 2016). Microsoft Developer Network. Recuperado el Octubre de 31 de 2017, de https://msdn.microsoft.com/es-es/library/mt162307.aspx
