Documentar con YUIDoc y GruntJS

Existen muchas herramientas para poder generar una buena documentación de código en JavaScript hoy en día.

En este caso hablaremos y veremos el uso de una buena herramienta llamada YUIDoc y proviene de la familia de YUI (Yahoo User Interface), con ello podemos hacer que nuestro código tenga un valor agregado.

Requisitos:

Necesitamos tener instalado el servidor nodejs, en caso no lo tengas instalado y estás bajo debian puedes visitar este buen post.

Luego necesitamos instalar GruntJS, aquí también puedes ver como instalarlo aqui.

Escenario:

Tengo un archivo llamado calculadora.js y se encuentra en la siguiente ruta

/home/dru/Projects/JS/docmycode/src/calculadora.js

y  su unica función es hacer de una simple calculadora :

var calculadora = function(){

};
calculadora.prototype.sumar = function(a, b){
 return a + b;
};
calculadora.prototype.restar = function(a, b){
 return a - b;
};
calculadora.prototype.multiplicar = function(a, b){
 return a * b;
};
calculadora.prototype.dividir = function(){
 return a / b;
};

Por el momento solo realiza operaciones muy básicas y como podemos ver: todos los métodos de la calculadora sólo reciben 2 parámetros.

Estableciendo el entorno de trabajo con las herramientas necesarias

OJO: Ten en cuenta que antes de seguir y ejecutar los comandos de cada paso debes ubicarte en la carpeta docmycode y para que esteas seguro de ello debes ejecutar este comando:

$ pwd

Paso 1
Creamos nuestro archivo package.json pero de una manera práctica que es ejecutando en consola o terminal el siguiente comando, si ya lo tienes creado previamente entonces puedes saltar al paso 2 :

$ npm init

Con el comando anterior te generará una serie de preguntas para que formes un archivo llamado package.json como standard propio de un paquete para el npm (Node Package Manager), pero en nuestro caso será para manejar nuestro pequeña demo, aqui mi pantalla una vez ejecutado ese comando:

demo-terminal

Tenemos nuestro archivo package.json generado, luego tenemos que agregarle los paquetes necesarios para usar el documentador con GruntJS

Paso 2
Editamos el package.json creando un nuevo nodo llamado “devDependencies” agregando los paquetes necesarios que son grunt, grunt-cli, y  YUIDoc

quedando así:

package-yuidoc

Paso 3
Teniendo nuestras dependencias y estando en la carpeta donde está nuestro archivo package.json ejecutamos en terminal o en consola el siguiente comando:

$ npm install

Haciendo ello instalamos los paquetes indicados en el paso 2 y nos quedaría un último paso que es configurar el automatizador.

Paso 4
Creamos un archivo llamado Gruntfile.js dentro de nuestra carpeta docmycode, y en ella ingresamos lo siguiente:

module.exports = function(grunt){
 //establecemos la configuración para el grunt en si
 grunt.initConfig({
   //pasándole con un nodo con nombre pkg
   //se puede trabajar las variables del archivo package.json
   //y poder pasarlos a otras configuraciones
   pkg: grunt.file.readJSON('package.json'),
   //estableciendo la configuración para el YUIDoc
   //este nodo servirá para ejecutar la tarea de documentar
   yuidoc:{
     all: {
        //Aqui se está usando el nodo pkg indicado arriba
        name: '<%= pkg.name %>',
        description: '<%= pkg.description %>',
        version: '<%= pkg.version %>',
        url: '<%= pkg.homepage %>',
        options:{
          //leerá nuestra carpeta src donde está el archivo calculadora.js
          paths: ['src'],
          //creará una carpeta llamada docs donde estará lo que documentemos
          outdir: './docs/'
        }
     }
   }
 });

 grunt.log.write("Iniciando GruntJS");
 //cargando el contrib de YUIDoc
 grunt.loadNpmTasks('grunt-contrib-yuidoc');
 //adicionando la tarea yuidoc a ser la tarea por defecto en grunt
 grunt.registerTask('default', 'yuidoc');
};

Paso 5
Teniendo esa pequeña configuración ya podemos ejecutar este comando en consola:

$ grunt

En donde verás en la carpeta docs y en ella se encuentra un archivo de nombre index.html y abriendolo en un navegador podemos apreciar esto por el momento.

yui-browser

Documentando con YUIDoc
Cuando empezamos un comentario que entienda YUIDoc debe contener al inicio “/**” o también se pueden usar los estilos de comentar.

Teniendo claro ello, YUIDoc tiene una jerarquía de uso de etiquetas, las clasifica en primarias y secundarias.

Guiándonos de lo que indica la sintaxis de documentar y  de cómo documentar podemos usarlo con nuestro pequeño script llamado calculadora si lo tomamos como una clase lo actualizamos comentándolo así:

/**
 * Clase donde realizamos cálculos básicos
 *
 * @class calculadora
 * @constructor
 */
 var calculadora = function(){

 };

Y al método “sumar”:

/**
 * Retorna el resultado de la suma de 2 valores ingresados
 * @method sumar
 * @param {Integer} a El 1er valor a sumar
 * @param {Integer} b El 2do valor a sumar
 * @return {Integer} la suma de a y b
 */
calculadora.prototype.sumar = function(a, b){
 return a + b;
};

Continuando con los métodos restantes:

/**
 * Retorna el resultado de la resta de 2 valores ingresados
 * @method restar
 * @param {Integer} a El 1er valor a restar
 * @param {Integer} b El 2do valor a restar
 * @return {Integer} la resta de a y b
 */
calculadora.prototype.restar = function(a, b){
 return a - b;
};

/**
 * Retorna el resultado de la multiplicación de 2 valores ingresados
 * @method multiplicar
 * @param {Integer} a El 1er valor a multiplicar
 * @param {Integer} b El 2do valor a multiplicar
 * @return {Integer} la multiplicación de a y b
 */
calculadora.prototype.multiplicar = function(a, b){
 return a * b;
};

/**
 * Retorna el resultado de la división de 2 valores ingresados
 * @method dividir
 * @param {Integer} a El 1er valor a dividir
 * @param {Integer} b El 2do valor a dividir
 * @return {Integer} la división de a y b
 */
calculadora.prototype.dividir = function(){
 return a / b;
};

Y luego volvemos al terminal y ejecutamos:

$ grunt

Documentando hasta ahora debería salir algo como esto:documentando-con-yuidoc

Como se puede apreciar la forma de comentar para YUIDoc nos da muchas facilidades para tener una documentación agradable para el usuario.