Javadoc es un generador de documentación creado por Sun Microsystems para el lenguaje Java (ahora propiedad de Oracle Corporation ) con el fin de generar documentación de API en formato HTML a partir del código fuente de Java . El formato HTML se utiliza para agregar la comodidad de poder crear hipervínculos entre documentos relacionados. [1]
El formato de "comentarios de documentación" [2] utilizado por Javadoc es el estándar de facto de la industria para documentar clases Java. Algunos IDE , [3] como IntelliJ IDEA , NetBeans y Eclipse , generan automáticamente plantillas Javadoc. Muchos editores de archivos ayudan al usuario a producir el código fuente de Javadoc y utilizan la información de Javadoc como referencias internas para el programador.
Javadoc también proporciona una API para crear doclets y taglets, lo que permite a los usuarios analizar la estructura de una aplicación Java. De esta manera, JDiff puede generar informes sobre los cambios que se produjeron entre dos versiones de una API.
Javadoc no afecta el rendimiento en Java, ya que todos los comentarios se eliminan en el momento de la compilación. Escribir comentarios y Javadoc sirve para comprender mejor el código y, por lo tanto, para mantenerlo mejor.
Javadoc fue uno de los primeros generadores de documentación del lenguaje Java . [4] Antes del uso de generadores de documentación, era habitual utilizar escritores técnicos que normalmente escribían solo documentación independiente para el software, [5] pero era mucho más difícil mantener esta documentación sincronizada con el software en sí.
Java ha utilizado Javadoc desde el primer lanzamiento y normalmente se actualiza con cada nueva versión del Java Development Kit .
La @fieldsintaxis de Javadoc ha sido emulada por sistemas de documentación para otros lenguajes, incluido el sistema multilenguaje Doxygen , el sistema JSDoc para JavaScript, EDoc para Erlang y HeaderDoc de Apple .
Un comentario de Javadoc se separa del código mediante etiquetas de comentario estándar de varias líneas /*y */. La etiqueta de apertura (llamada delimitador de inicio de comentario) tiene un asterisco adicional, como en /**.
@param)@return)@throws)@see(una etiqueta "ver también")La mayoría de los comentarios de Javadoc están incrustados dentro de /** ... */las etiquetas. El bloque de comentarios de Javadoc se ubica inmediatamente encima de los elementos sin ninguna nueva línea de separación y debajo de cualquier declaración de importación. La declaración de clase generalmente contiene:
// declaraciones de importación/** * @author Nombre Apellido <dirección @ ejemplo.com> * @version 1.6 (número de versión actual del programa) * @since 1.2 (la versión del paquete al que se agregó esta clase por primera vez) */ public class Test { // cuerpo de la clase } Los comentarios de la documentación de los métodos suelen contener una descripción breve y concisa de una línea para explicar lo que hace el elemento, seguida de una descripción más larga y, por último, una sección de etiquetas que enumera los argumentos de entrada aceptados y los valores de retorno del método. El Javadoc se trata como HTML, por lo que <p>se puede utilizar una etiqueta de salto de párrafo " " para indicar varios párrafos.
/** * Descripción breve de una línea. (1) * <p> * Descripción más larga. Si hubiera alguna, sería (2) * aquí. * <p> * Y más explicaciones a continuación en párrafos consecutivos * separados por saltos de párrafo HTML. * * @param variable Descripción texto texto texto. (3) * @return Descripción texto texto texto. */ public int methodName (...) { // cuerpo del método con una declaración de retorno } Las variables se documentan de manera similar a los métodos, pero a menudo carecen de las etiquetas al final del comentario.
/** * Descripción de la variable aquí. */ private int debug = 0 ; No se recomienda [6] definir múltiples variables en un solo comentario de documentación, ya que Javadoc lee cada variable y las coloca por separado en la página HTML generada con el mismo comentario de documentación que se copia para todos los campos.
/** * Las distancias horizontales y verticales del punto (x,y) */ public int x , y ; // EVITAR En lugar de ello, se recomienda escribir y documentar cada variable por separado:
/** * La distancia horizontal del punto. */ public int x ; /** * La distancia vertical del punto. */ public int y ; Algunas de las etiquetas Javadoc disponibles [7] se enumeran en la siguiente tabla:
A continuación se muestra un ejemplo de Javadoc para documentar un método. Observe que el espaciado y la cantidad de caracteres en este ejemplo son los establecidos por las convenciones [ se necesita una aclaración ] .
/** * Valida un movimiento de ajedrez. * * <p>Use {@link #doMove(int fromFile, int fromRank, int toFile, int toRank)} para mover una pieza. * * @param fromFile archivo desde el que se mueve una pieza * @param fromRank rango desde el que se mueve una pieza * @param toFile archivo al que se mueve una pieza * @param toRank rango al que se mueve una pieza * @return true si el movimiento es válido, falso en caso contrario * @since 1.0 */ boolean isValidMove ( int fromFile , int fromRank , int toFile , int toRank ) { // ...body } /** * Mueve una pieza de ajedrez. * * @see java.math.RoundingMode */ void doMove ( int fromFile , int fromRank , int toFile , int toRank ) { // ...body } Los programas Doclet funcionan con la herramienta Javadoc para generar documentación a partir del código escrito en Java . [8]
Los doclets se escriben en el lenguaje de programación Java y se utilizan Doclet APIpara:
El StandardDoclet[1] incluido con Javadoc genera documentación de API como archivos HTML basados en marcos . Hay muchos doclets no estándar disponibles en la web [ cita requerida ] , a menudo de forma gratuita. Se pueden utilizar para:
Cuando hice el JavaDoc original en el compilador original, incluso la gente cercana a mí lo criticó bastante. Y fue interesante, porque la crítica habitual era: un buen escritor técnico podría hacer un trabajo mucho mejor que el que hace JavaDoc. Y la respuesta es, bueno, sí, pero ¿cuántas API están realmente documentadas por buenos escritores técnicos? ¿Y cuántos de ellos realmente actualizan su documentación con la frecuencia suficiente para que sea útil?