Cómo Generar Documentación en JavaScript

From Wiki de Caballero
Jump to navigation Jump to search

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

Se usa para aplicarle un template a JSDoc.

Instalación

  1. Descargar DocStrap de https://github.com/terryweiss/docstrap/archive/master.zip.
  2. Descomprimir DocStrap en el directorio del primer paso (/opt/local/etc/jsdoc).
  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 ~/.profile, se agrega el código al archivo. Puede ser en otros archivos, lo importante es que sea uno que se ejecute cuando se inicie una sesión en el terminal (el archivo ~/.profile solo se ejecuta cuando se ingrese al home de la persona donde está el archivo).

Uso

El uso es el mismo que el de JSDoc pero se usan ubicaciones de DocStrap, con las variables que se crearon en el punto anterior, se usa de la siguiente manera:

jsdoc js.js -t $JSDOC_DOCSTRAP_TEMPLATE_DIR -c $JSDOC_DOCSTRAP_CONFIG -d /directorio/donde/se/guarda/documentacion/

Recomendaciones

  1. Se puede agregar el anterior comando en un archivo ejecutable para cada proyecto que requiera documentación de JavaScript. Se crea un archivo de Bash, se agrega la línea del comando a ejecutar y se cambia el output a la ubicación deseada.
  2. En el ejemplo anterior sobre el uso, se usa un archivo de configuración por defecto ubicado en el mismo directorio de DocStrap. Se puede usar el mismo archivo para todos los proyectos o se puede crear un archivo nuevo para cada proyecto en particular. Para esto copiar el archivo por defecto y modificarlo a voluntad, luego se invoca en el comando.

Cómo Documentar

Namespaces

A continuación un ejemplo de cómo documentar namespaces, se usa @namespace y @memberof (aunque se pueden usar otras etiquetas). No es un ejemplo perfecto ya que la documentación de los requisitos no es muy clara, este ejemplo funciona pero puede ser que hayan cosas que le falten o que le sobren.

Este ejemplo se basa parcialmente en How do I JSDoc A Nested Object's Methods?.

/**
 * Un namespace, descripción.
 *
 * @namespace
 */
var estoEsUnNamespace = {
	/**
	 * Esto es un namespace que hace parte de otro.
	 * 
	 * @namespace subNamespace
	 * @memberOf estoEsUnNamespace
	 */
	subNamespace: {
		/**
		 * Esto es un string y se llama stringX..
		 *
		 * @memberof estoEsUnNamespace.subNamespace
		 */
		stringX: 'Esto es un string y se llama X',
		/**
		 * Esto es una función y se llama functionY.
		 * 
		 * @memberof estoEsUnNamespace.subNamespace
		 */
		functionY: function () {
			alert('Esto es un alert adentro de functionY.');
		}

	}
}

Notas

  • Al momento de documentar, no usar palabras reservadas (aunque hagan parte de otra palabra como functionParam) ya que aparentemente ApiGen se "marea" y no es capaz de tomar la palabra como única.

Referencias