Hispanopedia Wiki
Articulo de referencia

Javadoc

Javadoc (también escrito con mayúscula inicial como JavaDoc o javadoc ) es un generador de documentación de API para el lenguaje de programación Java . A partir de la informació...

Hispanopedia WikiContenido en espanolLectura gratuita

Javadoc (también escrito con mayúscula inicial como JavaDoc o javadoc ) es un generador de documentación de API para el lenguaje de programación Java . A partir de la información del código fuente de Java , Javadoc genera documentación formateada en HTML y otros formatos mediante extensiones . [ 1 ] Javadoc fue creado por Sun Microsystems y actualmente pertenece a Oracle .

El contenido y el formato de un documento resultante se controlan mediante un marcado especial en los comentarios del código fuente . Como este marcado es un estándar de facto y omnipresente para documentar código Java, [ 2 ] muchos IDE extraen y muestran la información Javadoc mientras visualizan el código fuente, a menudo al pasar el cursor sobre un símbolo asociado. Algunos IDE, como IntelliJ IDEA , NetBeans y Eclipse , admiten la generación de bloques de comentarios de plantilla Javadoc. [ 3 ] La @tagsintaxis del marcado Javadoc ha sido reutilizada por otros generadores de documentación, incluidos Doxygen , JSDoc , EDoc y HeaderDoc .

Javadoc admite extensiones mediante doclets y taglets, que permiten generar diferentes formatos de salida y realizar análisis estáticos del código fuente . Por ejemplo, JDiff informa sobre los cambios entre dos versiones de una API.

Aunque algunos critican Javadoc y los generadores de documentación de API en general, una motivación para crear Javadoc fue que la documentación de API más tradicional (menos automatizada) a menudo está desactualizada o no existe debido a limitaciones comerciales como la disponibilidad limitada de redactores técnicos . [ 4 ]

Javadoc ha sido parte de Java desde su primera versión y se actualiza con frecuencia con cada versión del Kit de Desarrollo de Java . [ 5 ]

La documentación Javadoc y los comentarios en el código fuente que utiliza Javadoc no afectan al rendimiento de un ejecutable Java, ya que el compilador ignora los comentarios.

Margen

Javadoc ignora los comentarios a menos que estén marcados especialmente. Un comentario Javadoc se marca con un asterisco adicional después del inicio de un comentario de varias líneas: /**. Las líneas siguientes van precedidas de un *, y todo el bloque de comentarios debe terminar con un */.

A continuación se muestra un ejemplo de comentario Javadoc de un método:

/** * Descripción de lo que hace el método. * * @param input Descripción del parámetro. * @return Descripción del valor de retorno. * @throws Exception Descripción de la excepción. */ public int methodName ( String input ) throws Exception { ... }

Algunas etiquetas HTML , como <p>, <head>, y <nav>, son compatibles con Javadoc.

Reducción

Desde Java 23 en adelante, Javadoc admite el estándar Markdown CommonMark en las líneas de comentarios que comienzan con ///en lugar del formato multilinea anterior. [ 6 ]

Doclets

Un programa Doclet trabaja con Javadoc para seleccionar qué contenido incluir en la documentación, formatear la presentación del contenido y crear el archivo que contiene la documentación. [ 7 ] Un Doclet está escrito en Java y utiliza el Doclet API,

ElStandardDocletJavadoc, incluido en el código, genera documentación de API como archivos HTML basados ​​en marcos . Existen otros Doclets disponibles en la web , a menudo de forma gratuita. Estos se pueden utilizar para:

Etiquetas

Algunas de las etiquetas Javadoc disponibles [ 8 ] se enumeran en la tabla siguiente:

Véase también

Referencias

  1. ↑ "Javadoc" . agile.csc.ncsu.edu . Archivado del original el 13 de junio de 2017. Consultado el 12 de enero de 2022 .
  2. ↑ "javadoc - El generador de documentación de la API de Java" . Sun Microsystems . Consultado el 30 de septiembre de 2011 ..
  3. ↑ IntelliJ IDEA , NetBeans Archivado el 5 de abril de 2017 en Wayback Machine y Eclipse
  4. ↑ Venners, Bill; Gosling, James; et al. (2003-07-08). "Visualizing with JavaDoc" . artima.com . Recuperado el 19 de enero de 2013. 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 técnico 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 técnicos? ¿Y cuántos de ellos actualizan su documentación con la suficiente frecuencia como para ser útiles? 
  5. ↑ "Cómo escribir comentarios de documentación para la herramienta Javadoc" . Sun Microsystems . Consultado el 30 de septiembre de 2011 ..
  6. ↑ "JEP 467: Comentarios de documentación en Markdown" . OpenJDK . 11 de septiembre de 2023. Consultado el 10 de septiembre de 2025 .
  7. ↑ "Resumen del documento" .
  8. ↑ Especificación de comentarios de la documentación de JavaSE 13
  • Página principal de la herramienta Javadoc
  • Guía Javadoc de la plataforma Java, edición estándar
  • Actualización de la tecnología de etiquetas Javadoc JSR 260 Solicitud de especificación Java (define nuevas etiquetas Javadoc)
  • Mejora de Javadoc con Ashkelon
  • Diversos documentos de Java convertidos al formato de Ayuda de Windows.