sábado, 25 de mayo de 2013

Documentando código Javascript con JsDoc3

JsDoc es un generador de documentación de código JavaScript que utiliza cierto formato de comentarios para auto generarla.

En primer lugar, descargaremos el zip de JsDoc desde aquí y luego lo descomprimimos en una ubicación donde vaya a ser "instalado". Por ejemplo /home/usuario/Development

Para saber si todo funciona correctamete, abrir una terminal, cambiar al directorio raiz de JsDoc (ej: cd /home/usuario/Development/jsdoc-master/) y correr la siguiente línea para ejecutar los tests de verificación:
./jsdoc -T
Si todo ha ido bien, tendremos un mensaje similar a este:

Finished in 6.475 seconds706 tests, 1594 assertions, 0 failures.................Finished in 0.028 seconds17 tests, 34 assertions, 0 failures

Otra forma de instalarlo es ejecutando en consola:
sudo apt-get install jsdoc-toolkit
Esta segunda opción trae algunos cambios, que se marcarán como [Op2].


Ahora, para generar algo realmente vamos a hacer una prueba con código. Para ello vamos a utilizar este archivo, donde se pueden encontrar algunos tags específicos para indicar la descripción de una clase, sus parámetros de entrada, su return, entro otros. La lista completa de tags que se pueden utilizar puede ser consultada aquí

Para generar la documentación se debe ejecutar la siguiente línea, siempre reemplazando los directorios por los tuyos (yo muestro un ejemplo según mi archivo y directorios): 

./jsdoc /home/usuario/Desktop/prueba.js --destination /home/usuario/Desktop/out

[OP2]:
jsdoc /home/gaby/Desktop/prueba.js --directory=/home/user/Desktop/out 

También puede generarse sin especificar el parámetro "--destination" o "--directory", en cuyo caso la documentación se generará y quedará almacenada en la carpeta /out del directorio de la aplicación JsDoc (en mi caso /home/usuario/Development/jsdoc-master/out).

Por defecto, JSDoc usará la plantilla "default" para convertir los comentarios en HTML, pero es posible editar esta plantilla para adaptarla a otras necesidades, o crear una plantilla totalmente nueva.