Javadoc
| ||||
Javadoc. Es una herramienta de Sun para documentar el código mediante comentarios, pero ala vez provee una herramienta que permite extraer esa documentación deforma que sea útil para el usuario de la misma.
Básicamente javadoc es un programa, que toma lo comentarios que se colocan en el código con marcas especiales y construye un archivo HTML con clases, métodos y la documentación que corresponde. Este HTML tiene el formato de toda la documentación estándar de Java provista por Sun.
La documentación a ser utilizada por javadoc se escribe en comentarios que comienzan con /** (notar el doble *) y que terminan con */. A la vez, dentro de estos comentarios se puede escribir código HTML y operadores para que interprete javadoc (generalmente precedidos por @)
Uso de etiquetas
Para generar APIs con Javadoc han de usarse etiquetas (tag's) de HTML o ciertas palabras reservadas precedidas por el caracter "@".
Estas etiquetas se escriben al principio de cada clase, miembro o método, dependiendo de qué objeto se desee describir, mediante un comentario iniciado con "/**" y acabado con "*/".
Algunas de las palabras reservadas - puede verse una lista completa de las tags con su correpondiente uso en sun.com
Nota 1: En uso explica la semántica del texto tras el tag.
Nota 2: Versión indica desde qué versión de Javadoc es válida.
Tag Descripción Uso Versión @author Nombre del desarrollador. nombre_autor 1.0 @deprecated Indica que el método o clase es antigua y que no se recomienda su uso porque posiblemente desaparecerá en versiones posteriores. descripción 1.0 @param Definición de un parámetro de un método, es requerido para todos los parámetros del método. nombre_parametro descripción 1.0 @return Informa de lo que devuelve el método, no se puede usar en constructores o métodos "void". descripción 1.0 @see Asocia con otro método o clase. referencia (#método(); clase#método(); paquete.clase; paquete.clase#método()). 1.0 @throws Excepción lanzada por el método nombre_clase descripción 1.2 @version Versión del método o clase. versión 1.0
Enlaces externos
- Myjavadoc. Buscador de Javadocs online - permite encontrar la documentación Javadoc de una clase a partir de su nombre. [citado 2011 Septirmbre del 2011]. Disponible en "myjavadoc.net".
Fuentes
- Artículo Documentando con javadoc. Disponible en: "luauf.com". Consultado: 7 de septiembre del 2011.
- Javadoc. Página principal de Javadoc - incluye enlaces a documentacion de referencia y a tutoriales. [citado 2011 Septirmbre del 2011]. Disponible en "java.sun.com".
- Documentacion Documentacion de uso de Javadoc - describe la herramienta javadoc e incluye ejemplos de uso y etiquetas válidas para Windows. Disponible en: "java.sun.com". Consultado: 7 de septiembre del 2011.