Javadoc es una utilidad deOracle para la generación de documentación deAPIs en formatoHTML a partir de código fuenteJava. Javadoc es el estándar de la industria para documentar clases deJava. La mayoría de losIDEs los generan automáticamente.
Javadoc también proporciona una API para creardoclets ytaglets, que le permite analizar la estructura de una aplicación Java. Así es comoJDiff puede generar informes de lo que ha cambiado entre dos versiones de una API.[1]
Para generarAPI con Javadoc han de usarse etiquetas (tags) deHTML o ciertas palabras reservadas precedidas por el carácter "@".
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 "*/".
A continuación se explican algunas de las palabras reservadas - puede verse una lista completa de las tags con su correspondiente uso enoracle.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 |
| @version | Versión del método o clase. | versió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 |
| @throws | Excepción lanzada por el método, posee un sinónimo de nombre @exception | nombre_clase descripción | 1.2 |
| @see | Asocia con otro método o clase. | referencia (#método(); clase#método(); paquete.clase; paquete.clase#método()). | 1.0 |
| @since | Especifica la versión del producto | indicativo numerico | 1.2 |
| @serial | Describe el significado del campo y sus valores aceptables. Otras formas válidas son @serialField y @serialData | campo_descripcion | 1.2 |
| @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 |
Un ejemplo de un Javadoc de un método.
/** * Inserta un título en la clase descripción. * Al ser el título obligatorio, si es nulo o vacío se lanzará * una excepción. * * @param titulo El nuevo título de la descripción. * @throws IllegalArgumentException Si titulo es null, está vacío o contiene sólo espacios. */publicvoidsetTitulo(Stringtitulo)throwsIllegalArgumentException{if(titulo==null||titulo.isBlank()){thrownewIllegalArgumentException("El título no puede ser nulo o vacío");}else{this.titulo=titulo;}}
| Control de autoridades |
|
|---|
Datos:Q1413077