Javadoc es un generador de documentación creado por Sun Microsystems para el lenguaje Java (ahora propiedad de Oracle Corporation ) para generar documentación API en formato HTML a partir del código fuente Java . El formato HTML se utiliza para agregar la conveniencia de poder vincular documentos relacionados entre sí. [1]
El formato de "comentarios de documentos" [2] utilizado por Javadoc es el estándar industrial de facto para documentar clases de Java. Algunos IDE , [3] como IntelliJ IDEA , NetBeans y Eclipse , generan automáticamente plantillas Javadoc. Muchos editores de archivos ayudan al usuario a producir código fuente Javadoc y utilizan la información Javadoc como referencia interna para el programador.
Javadoc también proporciona una API para crear doclets y taglets, que permite a los usuarios analizar la estructura de una aplicación Java. Así es como JDiff puede generar informes de lo que cambió 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 así 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 redactores 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 la primera versión y, por lo general, se actualiza con cada nueva versión del kit de desarrollo de Java .
La @fieldsintaxis de Javadoc ha sido emulada por sistemas de documentación para otros lenguajes, incluido el multilingüe Doxygen , el sistema JSDoc para JavaScript y HeaderDoc de Apple .
Un comentario Javadoc se separa del código mediante etiquetas de comentarios 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 estructura básica para escribir comentarios de documentos es incrustarlos en su interior /** ... */. El bloque de comentarios de Javadoc se coloca inmediatamente encima de los elementos sin ninguna nueva línea de separación. Tenga en cuenta que cualquier declaración de importación debe preceder a la declaración de clase. La declaración de clase suele contener:
// importar declaraciones/** * @author Nombre Apellido <dirección @ ejemplo.com> * @versión 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 clase } Para los métodos hay (1) una descripción breve y concisa de una línea para explicar lo que hace el elemento. A esto le sigue (2) una descripción más larga que puede abarcar varios párrafos. Los detalles se pueden explicar en su totalidad aquí. Esta sección es opcional. Por último, hay (3) una sección de etiquetas para enumerar los argumentos de entrada aceptados y los valores de retorno del método. Tenga en cuenta que todo el Javadoc se trata como HTML, por lo que las secciones de varios párrafos están separadas por una <p>etiqueta de salto de párrafo " ".
/** * Descripción breve de una línea. (1) * <p> * Descripción más larga. Si hubiera alguno, sería (2) * aquí. * <p> * Y aún más explicaciones a seguir en párrafos * consecutivos separados por saltos de párrafo HTML. * * @param variable Descripción texto texto texto. (3) * @return Texto de descripción texto texto. */ public int nombre_método (...) { // cuerpo del método con una declaración de retorno } Las variables se documentan de manera similar a los métodos con la excepción de que se omite la parte (3). Aquí la variable contiene sólo la breve descripción:
/** * Descripción de la variable aquí. */ depuración int privada = 0 ; Tenga en cuenta que no se recomienda [6] definir múltiples variables en un solo comentario de documentación. Esto se debe a 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 horizontal y vertical 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. */ público 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. Tenga en cuenta que el espaciado y la cantidad de caracteres en este ejemplo son los establecidos por las convenciones.
/** * Valida una jugada de ajedrez. * * <p>Utiliza {@link #doMove(int fromFile, int fromRank, int toFile, int toRank)} para mover una pieza. * * @param fromFile archivo desde el cual se mueve una pieza * @param fromRank rango desde el cual se mueve una pieza * @param toFile archivo al que se mueve una pieza * @param toRank rango al que se mueve una pieza * @return verdadero si el movimiento es válido, de lo contrario falso * @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 de código escrito en Java . [8]
Los doclets están escritos en el lenguaje de programación Java y se utilizan Doclet APIpara:
El StandardDoclet[1] incluido con Javadoc genera documentación API como archivos HTML basados en marcos . Muchos doclets no estándar están disponibles en la web [ cita requerida ] , a menudo de forma gratuita. Estos se pueden utilizar para:
Cuando hice el JavaDoc original en el compilador original, incluso las personas cercanas a mí lo criticaron bastante.
Y fue interesante, porque la crítica habitual era: un buen redactor tecnológico podría hacer un trabajo mucho mejor que el JavaDoc.
Y la respuesta es, bueno, sí, pero ¿cuántas API están realmente documentadas por buenos redactores de tecnología?
¿Y cuántos de ellos actualizan su documentación con la frecuencia suficiente para que sea útil?