Cómo Generar Documentación en JavaScript

JSDoc

Una forma de documentar JavaScript es usar JSDoc para generar la documentación en html. Este software hace uso de una sintaxis similar a JavaDoc. A continuación los pasos para instalarlo y usarlo fácilmente.

Instalación

1. Crear directorio para mantener todo lo relacionado con JSDoc en /opt/local/etc/jsdoc (directorio sugerido).
2. Descargar JSDoc de https://github.com/jsdoc3/jsdoc/archive/master.zip.
3. Descomprimir en el directorio creado en el primer paso.
4. Agregar el ejecutable de JSDoc al PATH. Para esto se puede crear un link del ejecutable, por ejemplo corriendo el siguiente comando:

   sudo ln -s /opt/local/etc/jsdoc/jsdoc-3.2.2/jsdoc /usr/local/bin/jsdoc

Uso

El uso básico es sencillo, se llama JSDoc y se le pasa el parámetro de donde se quiere generar la documentación.

jsdoc js.js -d /directorio/donde/se/guarda/documentacion/

Para saber más sobre el uso ejecutar jsdoc --help.

DocStrap

Instalación

1. Descargar DocStrap de https://github.com/terryweiss/docstrap/archive/master.zip.
2. Descomprimir DocStrap en el directorio del primer paso.
3. Para el uso de DocStrap se usan algunos parámetros como su ubicación, en vez de escribir cada vez los directorios se usan variables para hacerlo más fácil. Para crear estas variables se hace con los siguientes comandos:

   export JSDOC_DOCSTRAP_DIR=/opt/local/etc/jsdoc/docstrap-master
   export JSDOC_DOCSTRAP_TEMPLATE_DIR=$JSDOC_DOCSTRAP_DIR/template/
   export JSDOC_DOCSTRAP_CONFIG=$JSDOC_DOCSTRAP_TEMPLATE_DIR/jsdoc.conf.json

4. En vez de ejecutar cada vez estos comandos es mejor ponerlos en algún archivo que lo haga automáticamente. Esto se puede hacer en diferentes partes, por ejemplo en ~/.profile, pero una mejor forma puede ser guardarlo en el archivo jsdoc (mencionado en el paso 4 de la instalaciónd e JSDoc), se agrega el código al principio del archivo.

Referencias

• http://usejsdoc.org/, cómo usar JSDoc.