El JAVADOC

JAVA DOC

¿Que es JAVADOC?

Es la herramienta de java integrada en el JDK (JAVA Development Kit) sirve para generar documentación básica para el programador a partir del código fuente. Se intenta evitar que la documentación que se genera mediante un editor de texto se quede rápidamente obsoleta cuando el programa continúa su desarrollo y no se tiene la disciplina/tiempo para mantener la documentación al día. Para ello, se pide a los programadores de Java que escriban la documentación básica (clases, métodos, etc.) en el propio código fuente (en comentarios), con la esperanza de que esos comentarios sí se mantengan actualizados cuando se cambia el código. La herramienta Javadoc extrae dichos comentarios y genera con ellos un juego de documentación en formato html.

¿Como funciona JAVADOC?

Su funcionamiento es sencillo: a medida que se codifica una clase se colocan comentarios delimitados por "/**" y "*/" para indicar inicio y fin del comentario respectivamente. En medio puede ir cualquier cantidad de texto con los caracteres que se desee. Dichos comentarios se colocan justo sobre la declaración de atributos y métodos públicos. Los comentarios colocados sobre métodos y atributos privados son ignorados por defecto, porque de todas formas dado el principio de abstracción del paradigma de programación orientada a objetos no tiene sentido saber para qué sirven si no son accesibles los archivos de las clases y organiza los documentos. En caso de haber herencia, incluye también los comentarios de los métodos y atributos heredados. También dispone de etiquetas y palabras especiales para ayudar a especificar mejor ciertas cosas como los parámetros de un método.
Eiquetas y palabras especiales

@author nombr	Indica el autor de la clase o método, pueden ponerse el numero de nombres como quiera en una sola etiqueta separados por ‘,’ o poniendo una etiqueta por autor.
@deprecated comentario	Indica cuando una API o parte de código es obsoleto, dando así una aviso de que pudieran provocarse incompatibilidades si se sigue utilizando.
@throws nombre-clase desc. @exception	Indica la excepción que puede ser lanzada por el método (nombre-clase) y da una descripción de la causa de su lanzamiento
{@link nombre etiqueta}	Inserta un enlace auto contenido que apunta a nombre, esta etiqueta acepta la misma sintaxis que la etiqueta @see, per genera un enlace auto contenido en vez de colocar el enlace en la sección “see also”.
@param parámetro descripción	Añade un parámetro y su descripción a la sección parameters del código HTML
@return descripción	Describe el tipo de dato que retorna un método
@see referencia	añade una cabecera que apunta a una referencia, la documentación puede contener las etiquetas que se quieran, la referencia puede ser una URL, un paquete de JAVA o un simple texto.
@since texto	Indica la versión del paquete utilizado para el código
@version texto	Versión de el programa o paquete generado