Javadoc (originalmente en formato JavaDoc ) [1] 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 de Java . El formato HTML se utiliza para agregar la conveniencia de poder vincular los documentos relacionados con hipervínculos . [2]
El formato de "comentarios de documentos" [3] utilizado por Javadoc es el estándar industrial de facto para documentar las clases de Java. Algunos IDE , [4] como IntelliJ IDEA , NetBeans y Eclipse , generan automáticamente Javadoc HTML. 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 etiquetas, 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 es para comprender mejor el código y, por lo tanto, mantenerlo mejor.
Historia
Javadoc fue uno de los primeros generadores de documentación en lenguaje Java . [5] Antes del uso de generadores de documentación, se acostumbraba utilizar redactores técnicos que normalmente escribían sólo documentación independiente para el software, [6] pero era mucho más difícil mantener esta documentación sincronizada con el propio software.
Java ha utilizado Javadoc desde la primera versión y, por lo general, se actualiza con cada nueva versión del Java Development Kit .
La @field
sintaxis de Javadoc ha sido emulada por sistemas de documentación para otros lenguajes, incluido Doxygen en varios lenguajes , el sistema JSDoc para JavaScript y HeaderDoc de Apple .
Arquitectura técnica
Estructura de un comentario de Javadoc
Un comentario de Javadoc se separa del código mediante etiquetas de comentario de varias líneas estándar /*
y */
. La etiqueta de apertura (llamada delimitador de comentario inicial) tiene un asterisco adicional, como en /**
.
- El primer párrafo es una descripción del método documentado.
- A continuación de la descripción hay un número variable de etiquetas descriptivas, que significan:
- Los parámetros del método (
@param
) - Lo que devuelve el método (
@return
) - Cualquier excepción que el método pueda arrojar (
@throws
) - Otras etiquetas menos comunes como
@see
(una etiqueta "ver también")
- Los parámetros del método (
Descripción general de Javadoc
La estructura básica para escribir comentarios en un documento es incrustarlos en su interior /** ... */
. El bloque de comentarios de Javadoc se coloca inmediatamente encima de los elementos sin ninguna línea nueva que los separe. Tenga en cuenta que cualquier declaración de importación debe preceder a la declaración de clase. La declaración de clase generalmente contiene:
// importar declaraciones/ ** * @author Firstname Lastname * @version 1.6 (número de versión actual del programa) * @since 1.2 (la versión del paquete a la 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 artículo. 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 etiqueta de salto de párrafo.
/ ** * Breve descripción de una línea. (1) *
* Descripción más larga. Si hubiera alguno, sería (2) * aquí. *
* E incluso más explicaciones para seguir 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, con la excepción de que se omite la parte (3). Aquí la variable contiene solo una breve descripción:
/ ** * Descripción de la variable aquí. * / depuración int privada = 0 ;
Tenga en cuenta que no se recomienda [7] definir varias 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 su lugar, 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 ;
Tabla de etiquetas Javadoc
Algunas de las etiquetas Javadoc disponibles [8] se enumeran en la siguiente tabla:
Etiqueta y parámetro | Uso | Se aplica a | Desde |
---|---|---|---|
@autor John Smith | Describe un autor. | Clase, interfaz, enumeración | |
{ @docRoot } | Representa la ruta relativa al directorio raíz del documento generado desde cualquier página generada. | Clase, interfaz, enumeración, campo, método | |
@version versión | Proporciona entrada de versión de software. Máximo uno por clase o interfaz. | Clase, interfaz, enumeración | |
@ desde que-texto | Describe cuándo existió esta funcionalidad por primera vez. | Clase, interfaz, enumeración, campo, método | |
@ver referencia | Proporciona un enlace a otro elemento de documentación. | Clase, interfaz, enumeración, campo, método | |
@param nombre descripción | Describe un parámetro de método. | Método | |
@return descripción | Describe el valor de retorno. | Método | |
@exception classname descripción @throws classname descripción | Describe una excepción que se puede generar con este método. | Método | |
@ descripción obsoleta | Describe un método obsoleto. | Clase, interfaz, enumeración, campo, método | |
{ @inheritDoc } | Copia la descripción del método reemplazado. | Método primordial | 1.4.0 |
{ @link reference } | Enlace a otro símbolo. | Clase, interfaz, enumeración, campo, método | |
{ @linkplain reference } | Idéntico a {@link}, excepto que la etiqueta del vínculo se muestra en texto sin formato que en fuente de código. | Clase, interfaz, enumeración, campo, método | |
{ @value #STATIC_FIELD } | Devuelve el valor de un campo estático. | Campo estático | 1.4.0 |
{ @code literal } | Formatea el texto literal en la fuente del código. Es equivalente a {@literal} . | Clase, interfaz, enumeración, campo, método | 1.5.0 |
{ @literal literal } | Denota texto literal. El texto adjunto se interpreta como que no contiene marcado HTML o etiquetas javadoc anidadas. | Clase, interfaz, enumeración, campo, método | 1.5.0 |
{ @serial literal } | Se utiliza en el comentario del documento para un campo serializable predeterminado. | Campo | |
{ @serialData literal } | Documenta los datos escritos por los métodos writeObject () o writeExternal (). | Campo, Método | |
{ @serialField literal } | Documenta un componente ObjectStreamField. | Campo |
Ejemplos de
A continuación, se muestra un ejemplo de Javadoc para documentar un método. Tenga en cuenta que el espaciado y el número de caracteres en este ejemplo son los que establecen las convenciones.
/ ** * Valida una jugada de ajedrez. * * Use {@link #doMove (int fromFile, int fromRank, int toFile, int toRank)} para mover una pieza.
* * @param fromFile file desde el cual se mueve una pieza * @param fromRank Rango desde el cual se mueve una pieza * @param toFile file al que se está moviendo una pieza * @param toRank rank al que se está moviendo una pieza * @return true 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. * * @ver java.math.RoundingMode * / void doMove ( int fromFile , int fromRank , int toFile , int toRank ) { // ... body }
Ver también
Referencias
- ^ Ahora encapsulado como 'Javadoc'. Ver [1] . Originalmente encajonado como 'JavaDoc'. Ver [2]
- ^ https://web.archive.org/web/20170613233020/http://agile.csc.ncsu.edu/SEMaterials/tutorials/javadoc/
- ^ "javadoc - El generador de documentación de la API de Java" . Sun Microsystems . Consultado el 30 de septiembre de 2011 ..
- ^ IntelliJ IDEA , NetBeans Archivado el 5 de abril de 2017 en Wayback Machine y Eclipse
- ^ "Cómo escribir comentarios de documentos para la herramienta Javadoc" . Sun Microsystems . Consultado el 30 de septiembre de 2011 ..
- ^ Venners, Bill; Gosling, James; et al. (8 de julio de 2003). "Visualización con JavaDoc" . artima.com . Consultado el 19 de enero de 2013 .
Cuando hice el JavaDoc original en el compilador original, incluso las personas cercanas a mí lo criticaron bastante profundamente. Y fue interesante, porque la crítica habitual era: un buen escritor de tecnología podría hacer un trabajo mucho mejor que el de JavaDoc. Y la respuesta es, bueno, sí, pero ¿cuántas API están realmente documentadas por buenos escritores de tecnología? ¿Y cuántos de ellos actualizan su documentación con la suficiente frecuencia para ser útiles?
- ^ "Plataforma Java, referencia de herramientas de edición estándar para Oracle JDK en Solaris, Linux y OS X, versión 8. Sección" Declaraciones de campos múltiples " " . Consultado el 20 de diciembre de 2017 .
- ^ Especificación de comentarios de documentación de JavaSE 13
enlaces externos
- Plataforma Java, Guía Javadoc de edición estándar
- JSR 260 Javadoc Tag Technology Update Java Specification Request (define nuevas etiquetas Javadoc)
- Mejora Javadoc con ashkelon
- Globaldocs: un visor para explorar múltiples Javadocs simultáneamente.
- Varias documentaciones de Java convertidas al formato de ayuda de Windows