Maven-javadoc-plugin

Qué es Maven Javadoc Plugin

Maven Javadoc Plugin es una herramienta esencial para proyectos Java que genera documentación a partir de los comentarios en el código fuente. En este tutorial, exploraremos algunas de las opciones avanzadas más útiles para optimizar y personalizar la generación de Javadoc en tu proyecto Maven.

Configuración Básica

Debes añadir el plugin maven-javadoc-plugin en tu pom.xml. Hay dos posibles sitios para hacerlo, dentro del bloque <reporting> o dentro del bloque <build>

Si lo haces dentro del bloque <reporting>, el documento javadoc se generará cuando generes la documentación web de tu proyecto con el comando mvn site. maven-site-plugin se encargará de generar el documento javadoc e incluirlo como un informe más en la documentación del proyecto.

Si lo haces en el bloque <build>, tendrás que generar la documentación javadoc con el comando mvn javadoc:javadoc, sin necesidad de generar la documentación completa del proyecto.

Puedes optar por una, por otra o por ambas, según tus necesidades. Veamoslas.

build plugins

Añade el plugin en la sección build de tu archivo `pom.xml`:

<project>
  ..
  <build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>3.6.2</version>
        </plugin>
        ..
    </plugins>
    ..
  </build>
  ..
</project>

reporting plugins

En la sección reporting

<project>
  ..
  <reporting>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>3.6.2</version>
        </plugin>
        ..
    </plugins>
    ..
  </reporting>
  ..
</project>

Configurar la generación de javadoc

Hay muchas opciones para configurar la generación de javadoc. Veamos algunas de ellas.

Excluir/Incluir Paquetes

Puedes especificar qué paquetes documentar o excluir utilizando los parámetros `excludePackageNames` y `includePackageNames` respectivamente:

  <configuration>
      <excludePackageNames>com.example.exclude.*</excludePackageNames>
      <includePackageNames>com.example.include.*</includePackageNames>
  </configuration>

Seleccionar Fuentes para Javadoc

maven-javadoc-plugin busca los fuentes para generar la documentación en los directorios habituales de un proyecto maven. Si los fuentes estuvieran ubicados en otros directorios, podemos indicar dónde están.

  <configuration>
      <sourcepath>my/path/src/java</sourcepath>
  </configuration>

Generar nuestra propia documentación

maven-javadoc-plugin usa una la clase StandardDoclet para generar la documentación html de nuestros fuentes java. Esta clase impelementa la interface jdk.javadoc.doclet.Doclet.

Si en un proyecto separado hacemos nuestra propia implementación de esa interface con una clase, por ejemplo DocletExample, podemos indicarle a maven-javadoc-plugin que la use en lugar de StandardDoclet. Esto nos permitirá generar la documentación a nuestro gusto o generar cualquier otro tipo de informe.

La configuración sería

  <configuration>
      <doclet>com.chuidiang.DocletExample</doclet>
      <docletArtifact>
          <groupId>com.chuidiang</groupId>
          <artifactId>maven-doclet</artifactId>
          <version>1.0-SNAPSHOT</version>
      </docletArtifact>
      <useStandardDocletOptions>false</useStandardDocletOptions>
          <additionalOptions>
              <additionalOption>-myCustomOption</additionalOption>
              <additionalOption>MyOption</additionalOption>
          </additionalOptions>
  </configuration>

Donde

• com.chuidiang.DocletExample es el nombre de la clase que implementa jdk.javadoc.doclet.Doclet
• com.chuidiang es el groupId del proyecto maven donde tenemos esa clase.
• maven-doclet es el artifactId del proyecto maven donde tenemmos esa clase.
• 1.0-SNAPSHOT es la version del proyecto maven donde tenemos esa clase.

Adicionalmente, hemos puesto

• useStandardDocletOptions a false. Si lo dejamos con su valor por defecto true, nuestra clase tendrá que tratar todas las opciones estándar de StandardDoclet. Poniéndolo a false no estamos obligados a tratar esas opciones.
• additionalOptions para añadir, si queremos, opciones propias para nuestra clase.

Ejemplo de implementación de jdk.javadoc.doclet

Conclusión

El Maven Javadoc Plugin ofrece una amplia variedad de opciones para personalizar la generación de documentación en tu proyecto. Al utilizar estas opciones avanzadas, puedes crear documentación más rica y adaptada a las necesidades específicas de tu aplicación Java. Experimenta con estas configuraciones para optimizar la documentación de tu código y facilitar la comprensión y colaboración en tu equipo de desarrollo.