Programación Orientada a Objetos: Documentación

La documentación consiste en escribir comentarios para explicar el código de manera clara, con el fin de que se entienda lo que hace, ya que con el puro código no es suficiente.

Sin la documentación, nos puede suceder que al momento de retomar el proyecto después de un tiempo, ni nosotros mismos le entendamos. La documentación es importante para que no solo nosotros entendamos, si no que cuando otro programador retome el proyecto logre entenderlo fácilmente.

Una herramienta que podemos utilizar para documentar en Java es Javadoc. Una ventaja es que al momento en que instalamos el JDK, Javadoc se instala. Javadoc nos genera la documentación en un archivo html.

Para poder documentar se utiliza lo siguiente:

/** Etiqueta */

Para formar la etiqueta primero se coloca @ y después la palabra reservada.

Las etiquetas más comunes son las siguientes:

Etiqueta	Descripción
@autor	Nombre del autor
@deprecated	Indica que la clase o método son antiguos
@param	Indica parámetro que recibe un método
@return	Indica lo que devuelve el método
@see	Asocia un método o una clase con otro
@throws	Excepción lanzada por método
@version	Versión de la clase o método

Ejemplo

/** 
        * @author José A. Mañas - fprg5000
        * @version 23.9.2005
        */
       public class Circulo {
           private double centroX;
           private double centroY;
          private double radio;
          /**
           * Constructor.
           * @param cx centro: coordenada X.
           * @param cy centro: coordenada Y.
           * @param r radio.
           */
          public Circulo(double cx, double cy, double r) {
              centroX = cx;
              centroY = cy;
              radio = r;
          }
          /**
           * Getter.
           * @return centro: coordenada X.
           */
          public double getCentroX() {
              return centroX;
          }
          /**
           * Calcula la longitud de la circunferencia (perimetro del circulo).
           * @return circunferencia.
           */
          public double getCircunferencia() {
              return 2 * Math.PI * radio;
          }
          /**
           * Desplaza el circulo a otro lugar.
           * @param deltaX movimiento en el eje X.
           * @param deltaY movimiento en el eje Y.
           */
          public void mueve(double deltaX, double deltaY) {
              centroX = centroX + deltaX;
              centroY = centroY + deltaY;
         }
          /**
           * Escala el circulo (cambia su radio).
           * @param s factor de escala.
           */
          public void escala(double s) {
              radio = radio * s;
          }
      }

Para generar la documentación ponemos lo siguiente en la terminal