Introducción a Javadoc

Programación

1. Información general

Una buena documentación de la API es uno de los muchos factores que contribuyen al éxito general de un proyecto de software.

Afortunadamente, todas las versiones modernas del JDK proporcionan la herramienta Javadoc, para generar documentación de API a partir de comentarios presentes en el código fuente.

Prerrequisitos:

  1. JDK 1.4 (se recomienda JDK 7+ para la última versión del complemento Maven Javadoc)
  2. La carpeta JDK / bin agregada a la variable de entorno PATH
  3. (Opcional) un IDE que con herramientas integradas

2. Comentarios de Javadoc

Empecemos por los comentarios.

La estructura de los comentarios de Javadoc se ve muy similar a un comentario regular de varias líneas , pero la diferencia clave es el asterisco adicional al principio:

// This is a single line comment /* * This is a regular multi-line comment */ /** * This is a Javadoc */

Los comentarios de estilo Javadoc también pueden contener etiquetas HTML.

2.1. Formato Javadoc

Los comentarios de Javadoc pueden colocarse encima de cualquier clase, método o campo que queramos documentar.

Estos comentarios normalmente se componen de dos secciones:

  1. La descripción de lo que estamos comentando.
  2. Las etiquetas de bloque independientes (marcadas con el símbolo " @ ") que describen metadatos específicos

Usaremos algunas de las etiquetas de bloque más comunes en nuestro ejemplo. Para obtener una lista completa de etiquetas de bloque, visite la guía de referencia.

2.2. Javadoc a nivel de clase

Echemos un vistazo a cómo se vería un comentario de Javadoc a nivel de clase:

/** * Hero is the main entity we'll be using to . . . * * Please see the {@link com.baeldung.javadoc.Person} class for true identity * @author Captain America * */ public class SuperHero extends Person { // fields and methods }

Tenemos una breve descripción y dos etiquetas de bloque diferentes: independientes y en línea:

  • Las etiquetas independientes aparecen después de la descripción con la etiqueta como la primera palabra en una línea, por ejemplo, la etiqueta @author
  • Las etiquetas en línea pueden aparecer en cualquier lugar y están rodeadas de llaves , por ejemplo, la etiqueta @link en la descripción.

En nuestro ejemplo, también podemos ver que se utilizan dos tipos de etiquetas de bloque:

  • {@link} proporciona un enlace integrado a una parte de nuestro código fuente a la que se hace referencia
  • @author el nombre del autor que agregó la clase, método o campo que se comenta

2.3. Javadoc a nivel de campo

También podemos usar una descripción sin etiquetas de bloque como esta dentro de nuestra clase SuperHero :

/** * The public name of a hero that is common knowledge */ private String heroName;

Los campos privados no tendrán Javadoc generado para ellos a menos que pasemos explícitamente la opción -private al comando Javadoc.

2.4. Javadoc a nivel de método

Los métodos pueden contener una variedad de etiquetas de bloque Javadoc.

Echemos un vistazo a un método que estamos usando:

/** * 
This is a simple description of the method. . . * Superman! * 
 * @param incomingDamage the amount of incoming damage * @return the amount of health hero has after attack * @see HERO-402 * @since 1.0 */ public int successfullyAttacked(int incomingDamage) { // do things return 0; }

El successfullyAttacked método contiene una descripción y numerosas etiquetas de bloque independiente.

Hay muchas etiquetas de bloque para ayudar a generar la documentación adecuada y podemos incluir todo tipo de información. Incluso podemos utilizar etiquetas HTML básicas en los comentarios.

Repasemos las etiquetas que encontramos en el ejemplo anterior:

  • @param proporciona cualquier descripción útil sobre el parámetro de un método o la entrada que debería esperar
  • @return proporciona una descripción de lo que un método devolverá o puede devolver
  • @see generará un vínculo similar a la etiqueta {@link} , pero más en el contexto de una referencia y no en línea.
  • @since especifica qué versión de la clase, campo o método se agregó al proyecto
  • @version especifica la versión del software, comúnmente utilizado con macros% I% y% G%
  • @throws se usa para explicar con más detalle los casos en que el software esperaría una excepción
  • @deprecated da una explicación de por qué el código fue desaprobado, cuándo pudo haber sido desaprobado y cuáles son las alternativas

Aunque ambas secciones son técnicamente opcionales, necesitaremos al menos una para que la herramienta Javadoc genere algo significativo.

3. Generación Javadoc

Para generar nuestras páginas de Javadoc, querremos echar un vistazo a la herramienta de línea de comandos que viene con el JDK y el complemento Maven.

3.1. Herramienta de línea de comandos de Javadoc

The Javadoc command line tool is very powerful but has some complexity attached to it.

Running the command javadoc without any options or parameters will result in an error and output parameters it expects.

We'll need to at least specify what package or class we want documentation to be generated for.

Let's open a command line and navigate to the project directory.

Assuming the classes are all in the src folder in the project directory:

[email protected]:~$ javadoc -d doc src\*

This will generate documentation in a directory called doc as specified with the –d flag. If multiple packages or files exist, we'd need to provide all of them.

Utilizing an IDE with the built-in functionality is, of course, easier and generally recommended.

3.2. Javadoc With Maven Plugin

We can also make use of the Maven Javadoc plugin:

   org.apache.maven.plugins maven-javadoc-plugin 3.0.0  1.8 1.8   ...

In the base directory of the project, we run the command to generate our Javadocs to a directory in target\site:

[email protected]:~$ mvn javadoc:javadoc

The Maven plugin is very powerful and facilitates complex document generation seamlessly.

Let's now see what a generated Javadoc page looks like:

We can see a tree view of the classes our SuperHero class extends. We can see our description, fields, and method, and we can click on links for more information.

A detailed view of our method looks like this:

3.3. Custom Javadoc Tags

In addition to using predefined block tags to format our documentation, we can also create custom block tags.

In order to do so, we just need to include a -tag option to our Javadoc command line in the format of ::.

In order to create a custom tag called @location allowed anywhere, which is displayed in the “Notable Locations” header in our generated document, we need to run:

[email protected]:~$ javadoc -tag location:a:"Notable Locations:" -d doc src\*

In order to use this tag, we can add it to the block section of a Javadoc comment:

/** * This is an example... * @location New York * @returns blah blah */

The Maven Javadoc plugin is flexible enough to also allow definitions of our custom tags in our pom.xml.

In order to set up the same tag above for our project, we can add the following to the section of our plugin:

...   location a Notable Places:   ...

This way allows us to specify the custom tag once, instead of specifying it every time.

4. Conclusion

Este tutorial de introducción rápida cubrió cómo escribir Javadocs básicos y generarlos con la línea de comandos de Javadoc.

Una forma más fácil de generar la documentación sería usar cualquier opción IDE incorporada o incluir el complemento Maven en nuestro archivo pom.xml y ejecutar los comandos apropiados.

Los ejemplos de código, como siempre, se pueden encontrar en GitHub.