Actualmente estoy realizando un programa con JavaScript y quería generar su documentación, entonces me puse a buscar alguna herramienta que me lo permitiera hacer, tipo javadoc o phpDocumentor de PHP, y encontré la aplicación JSDoc.
Para muchos usuarios que están familiarizados con el programa javadoc de Java para generar la documentación de las clases desarrolladas a partir de sus comentarios, les resultará sencilla de usar esta herramienta.
Al igual que javadoc, jsdoc nos permite documentar nuestros programas en JavaScript y posteriormente generar su documentación a partir de sus comentarios.
Para poder instalarlo se necesita Perl y también funciona en Windows si se tiene Perl instalado. En el caso de Windows se recomienda usar ActivePerl.
Una vez que se cuenta con Perl instaldo, procederemos a descargar e instalar jsdoc.
Puede ser descargado desde aquí.
En este caso, la versión que se encuentra vigente es la 1.10.2.
Ya que se cuenta con el archivo, procederemos a descomprimirlo. En el caso de Windows se puede usar WinZip, Winrar o cualquier otro programa para descomprimir archivos.
En el caso de GNU/Linux podremos realizar los siguiente:
Se creará el directorio JSDoc-1.10.2, al cual ingresaremos y ejecutaremos lo siguiente:
$ ./jsdoc.pl test.js
o también:
$ perl jsdoc.pl test.js
Si nos aparece algo semenjante a esto:
Deberemos instalar el módulo de Perl HTML::Template. Para hacer ésto, deberas ser root. En mi caso usaré el comando sudo, para los que no tengan este programa, deberán convertirse en root y posteriomente ejecutar el siguiente comando quitando la palabra sudo.
En caso de usar sudo
En caso de no usar sudo
$ perl -MCPAN -e 'install HTML::Template'
En caso de usar AcitvePerl para Windows
PPM> install HTML-Template
PPM>quit
Deberemos seguir las instrucciones que se nos van indicando.
Una vez que se encuentra instalado este módulo, ya tenemos listo jsdoc para poder usar.
Recuerden que para usar este comando se hará lo siguiente:
o también
$ cd /directorio/de/instalación/de/jsdoc/
$ ./jsdoc.pl archivo.js
Cuando se ejecuta este comando, se crea el directorio js_docs_out el cual contiene la documentación generada a travez de los comentarios del archivo.js. Para poder ver esta documentación bastará con abrir el archivo index.html del directorio js_docs_out con nuestro navegador favorito.
Para saber como usar este programa, las etiquetas permitidas y más detalles acerca de esta herramienta, les recomiendo su sitio principal, donde en la sección Tag Reference encontraremos las etiquetas permitidas y en la sección Usage la manera de comentar nuestros programas.
1 comentario:
Me parece muy interesante tu aporte y muy explicativo
Publicar un comentario