4 min de lectura

Hacer la documentación de una API puede llegar a ser muy tedioso, todos los programadores prefieren ir directo al grano, escribir su código y pasar de largo esta aburrida tarea. Para la fortuna de todos, actualmente existen un montón de herramientas para agilizar la documentación del código sin tener que dedicarle más del tiempo necesario. JSDoc es una de esas herramientas, al funcionar para Javascript (un lenguaje popular en la actualidad) la vuelve un foco de atención.

¿Qué es JSDoc?

JSDoc es un generador de documentación para el lenguaje de Javascript, muy similar a phpDocumentor o Javadoc que funciona para Java. JSDoc analiza el código Javascript y automáticamente genera una página HTML con la documentación en ella.

Algunas personas denominan a JSDoc como un lenguaje de marcado, que puede ser fácilmente integrado con cualquier IDE utilizado para desarrollo.

Instalación de JSDoc

Para poder usar JSDoc, es necesario descargar e instalarlo. Esto puede hacerse de manera global por medio del manejador de paquetes de NodeJs (se asume que el usuario ha instalado previamente  npm), con el siguiente comando:

En caso de que se requiera instalar de manera local (para su uso dentro de un proyecto específico) debe ser guardado en el archivo  package.json  con el siguiente comando:

Etiquetas de JSDoc

La documentación generada por JSDoc se crea con base a comentarios dentro del código fuente. Estos deben colocarse inmediatamente antes del código a documentar. Cada comentario debe comenzar con / ** y terminar con */  para ser reconocido por el analizador JSDoc. Después de iniciar un comentario se agrega un * por cada línea antes del cierre de comentario. En estas líneas, es donde deben ser agregadas las etiquetas.

JSDoc cuenta con una gran variedad de etiquetas, que permiten personalizar la documentación. Estas etiquetas van desde simples parámetros de una función, hasta objetos muy complejos.

A continuación se listan las etiquetas más utilizadas de esta herramienta:

  • @class

    Esta etiqueta define una función como un constructor, destinada a ser llamada con su nombre para devolver una instancia.
    @class {tipo} {nombre}

  • @description

    Proporciona una descripción general del segmento de código que se está documentando.
    @description Descripción del segmento

  • @param

    Especifica el nombre, el tipo y la descripción de un parámetro de una función o un método.
    @param {tipo} Descripción del parámetro

  • @property

    Esta etiqueta provee una forma de documentar fácilmente una lista de propiedades estáticas de una clase, namespace u otro objeto.
    @property {tipo} Nombre de la propiedad

  • @returns

    Documenta el valor de retorno de una función.
    @returns {tipo} Descripción

  • @type

    Ofrece información acerca del tipo de valor que puede ser contenido en un objeto o variable, entre otros.
    @type {tipo}

  • @typedef

    Esta etiqueta es útil para documentar tipos personalizados, especialmente si desea consultarlos repetidamente.
    @typedef {tipo} Nombre

Ejemplo de uso de JSDoc

En el siguiente ejemplo podemos ver como se utiliza JSDoc para una clase Cilindro, que contiene una función para calcular su volumen.

Generando la documentación de API con JSDoc

Una vez el código se encuentre correctamente comentado, ejecutamos la herramienta de JSDoc:

Hecho lo anterior se generan los archivos HTML de la documentación y son almacenados en automático en la ruta out/.

En la siguiente imagen se puede apreciar la pagina generada por JSDoc, que describe la clase Cilindro usada en el ejemplo, junto con su función para calcular el volumen.


Visualización de la documentación generada por JsDoc
En base al script, JsDoc genera una página HTML con la clase Cilindro, sus métodos y la descripción de sus propiedades

 

Para más ejemplos e información detallada, se sugiere visitar la página oficial de JSDoc, en la cual se describe todo a detalle:

http://usejsdoc.org/

Referencias.

  • JSDoc org. (s.f.). @use JSDoc. Recuperado el Octubre de 31 de 2017, de http://usejsdoc.org/
  • Microsoft. (Julio de 2016). Microsoft Developer Network. Recuperado el Octubre de 31 de 2017, de https://msdn.microsoft.com/es-es/library/mt162307.aspx
Compartir
I am a student in computer engineering. I am interested in the development of video games and artificial intelligence applied in robotics

DEJA UNA RESPUESTA

Please enter your comment!
Please enter your name here

This site uses Akismet to reduce spam. Learn how your comment data is processed.