Cecilia Urbina: Documentación y herramientas de desarrollo

Semana 4
Clase Programación Orientada a Objetos

Documentar código se refiere a escribir comentarios al código, explicando lo que se hace y como lo hace de manera que no solo la computadora entienda el código si no también los humanos.

Además de ser una muy buena practica de programación ya que los mismos desarrolladores pueden así darse cuenta si la estructura del programa esta siendo correcta o no, es muy importante ya que a la hora de querer añadir funcionalidades al programa se facilita saber donde agregar las funciones, métodos o clases, saber cual hereda a cual, etc., arreglar errores en el código, también cuando se añaden programadores al proyecto es más fácil para ellos ver la documentación que el código puro.

Lo que se debe de comentar en el código para hacer una documentación correcta es agregar comentarios a todo lo que se piense pudiera ser no tan evidente para otras personas y explicar porque se hace.

Esto se hace comentando de que se encarga una clase, un paquete, que es lo que hace un método y cuando se usa, para que se usa una variable, entre otras cosas.

En Javascript la documentación se puede hacer con la herramienta jsdoc-toolkit, que muestra de manera mas fácil la documentación en archivos html(paginas web).

Las etiquetas principales que se usan en jsdoc-toolkit son:

Lo primero que se debe de hacer para utilizarlo es descargarlo de la pagina oficial:

Una vez descargado se descomprime, pero para poder probarlo necesitamos crear un documento.js de ejemplo para generar la documentación, este ejemplo se tiene que guardar dentro de la carpeta descomprimida:


/**
* Shape is an abstract base class. It is defined simply
* to have something to inherit from for geometric
* subclasses
* @constructor
*/
function Shape(color){
this.color = color;
}

// Bind the Shape_getColor method to the Shape class
Shape.prototype.getColor = Shape_getColor;

/**
* Get the name of the color for this shape
* @returns A color string for this shape
*/
function Shape_getColor(){
return this.color;
}

/**
* Circle is a subclass of Shape
*/
function Circle(radius){
this.radius = radius;
}

/**
* A very rough value for pi
*/
Circle.PI = 3.14;

/**
* Get the radius of this circle
* @returns The radius of this circle
*/
function Circle_getRadius(){
return this.radius;
}

// Circle is a subclass of Shape
Circle.prototype = new Shape(null);

Ya que se tiene el documento ahora se crea la documentacion para esto tenemos que ubicarnos dentro de la carpeta adecuada en el terminal, en mi caso yo tengo mi carpeta descomprimida llamada jsdoc-toolkit-2.3.2 bueno en esa carpeta hay otra que se llama jsdoc-toolkit nos posisionamos ahi, es dentro de esa carpeta donde guarde el programa anterior, ahora escribo la línea siguiente en el terminal:

java -jar jsrun.jar app/run.js -a -t=templates/jsdoc ejemplo.js

que se ve de esta manera en mi terminal:

Ahora se a creado la documentacion dentro de la carpeta jsdoc-toolkit-2.3.2>jsdoc-toolkit>out>jsdoc y es ahi donde se va a encontrar el index.html.

Y algunas capturas de pantalla: