Natural Docs: Una herramienta para generar documentación a partir del código fuente

Hace algunos días publiqué una herramienta llamada JSDoc, la cual funcionaba muy parecido al javadoc de Java. Pues bien, ésta es otra herramienta similar a la mencionada anteriormente, la gran diferencia es que esta funciona con una gran cantidad de lenguajes, entre los que podemos encontrar:

• C#
• Perl
• ActionScript
• C/C++
• Java
• PHP
• Python
• PL/SQL
• Visual Basic
• Pascal/Delphi
• Ada
• JavaScript
• Ruby
• Tcl
• ColdFusion
• Assembly
• Fortran (Formato free solamente)
• R
• Makefiles
• Plain text (Archivos de texto plano)

Un inconveniente que tiene JSDoc es que no puedes documentar las clases generadas con mootools o cuando creas objetos con JavaScript, por lo cual puede que no resulte útil para algunos desarrolladores. Pero como una muy buena alternativa se puede Natural Docs.

El único requerimiento para que funcione, es tener Perl.

Como dato, esta herramienta fue usada por el autor de mootools para generar su documentación junto con GeSHi.

JSDoc el javadoc para JavaScript

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:

$ tar -xzvf JSDoc-1.10.2.tgz

Se creará el directorio JSDoc-1.10.2, al cual ingresaremos y ejecutaremos lo siguiente:

$ cd JSDoc-1.10.2
$ ./jsdoc.pl test.js
o también:
$ perl jsdoc.pl test.js

Si nos aparece algo semenjante a esto:

Can't locate HTML/Template.pm in @INC (@INC contains:...

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

$ sudo perl -MCPAN -e 'install HTML::Template'

En caso de no usar sudo

$ su -
$ perl -MCPAN -e 'install HTML::Template'

En caso de usar AcitvePerl para Windows

C:\> ppm
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:

$ perl /directorio/de/instalación/de/jsdoc/jsdoc.pl archivo.js
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.

Visual Paradigm UML Community Edition en Ubuntu con Compiz Fusion

Actualización 2008-03-28:
También funciona para Debian y posiblemente para otras distribuciones omitiendo el uso del comando sudo. Ver este artículo si deseas usar el comando sudo en Debian.

Para iniciar la instalación lo primero que deberemos realizar es descargar "Visual Paradigm Community Edition" desde aquí.

Para poder descargar el software es necesario registrarse y solicitar una licencia la cuál será enviada por correo electrónico. Recuerda seleccionar la opción "Linux (122MB)" ya que ésta cuenta con su instalador.

Una vez que se cuenta con los archivos necesarios será necesario configurar la siguiente variable de ambiente AWT_TOOLKIT=MToolkit:

$ export AWT_TOOLKIT=MToolkit

Esta variable permite que no aparezca la pantalla de instalación totalmente en blanco y para evitar un problema similar podría colocarse esta variable en el archivo /etc/profile

Instalaremos los paquetes libmotif3 y libmotif-dev:

$ sudo apt-get install libmotif3 libmotif-dev

Ahora, para instalar el archivo se deberá ejecutar el archivo VP_Suite_Linux_3_2_20080206.sh

$ cd /directorio/donde/fue/descargado/el/archivo
$ sudo ./VP_Suite_Linux_3_2_20080206.sh

Se usa el comando sudo para permitir que sea instalado con privilegios de root, sino no se desea ejecutar con privilegios de root únicamente omitimos el comando sudo:

$ ./VP_Suite_Linux_3_2_20080206.sh

A continuación se mostrará la pantalla de instalación y se deberá presionar "Next"


aparecerá la pantalla donde se deberán aceptar la licencia y presionar "Next"


se deberá seleccionar la ruta donde se desea instalar "Visual Paradigm" y presionar "Next"


puede indicarse que se cree una enlace para los archivos ejecutables "Visual Paradigm" en la ubicación que queramos o puede seleccionarse la opción de no crear el enlace. Posteriormente presionar "Next"


ahora se deberá seleccionar todos los programas que se desean instalar, donde nada más elegiremos Visual Paradigm form UML (VP-UML) y presionar "Next"


en la sección "Edition": se deberá elegir "Community" y si se desea instalar la documentación en sus diversos formatos, y presionar "Next"


ahora se especifica que la licencia es "Single License Key" y donde se encuentra el archivo con la licencia que fue enviada por correo. Presionar "Next"


después aparecerá la pantalla de instalación de los archivos



Una vez terminado el proceso de instalación se presenta una pantalla donde se indica que quedó instalado y si se desea ejecutar


Si se desea ejecutar con posterioridad la aplicación deberá ejecutarse el comando:
$ /ruta/donde/se/instalo/VP_Suite3.2/bin/Visual_Paradigm_for_UML_6.2

por ejemplo:

$ /home/javoaxian/VP_Suite3.2/bin/Visual_Paradigm_for_UML_6.2

Con esto concluimos con la instalación de la aplicación y mostrando la pantalla de inicio de la aplicación, recuerden que antes de esta pantalla se pide donde será el área de trabajo del proyecto.