Maven javadoc plugin - ¿cómo puedo incluir solo ciertas clases?

Question

Al usar el plugin Maven javadoc puede excluir ciertos paquetes, pero tengo muchos paquetes y solo un puñado de clases para las que quiero producir Javadoc.

¿Hay alguna forma de incluir en lugar de excluir?

También me gustaría hacer cosas a nivel de clase en lugar de a nivel de paquete ya que tengo algunas clases en un paquete que necesitan javadoc y otras que no.

Answer 1

Al final he utilizado la opción de configuración sourcepath especificar dos paquetes que contienen las clases que quería Javadoc y di clases en aquellos paquetes que no quería Acceso predeterminado de Javadoc. Establecer la opción de configuración show en público me permitió elegir para qué clases Javadoc se creó al establecer el acceso al público.configuración completa a continuación:

<plugin> 
    <groupId>org.apache.maven.plugins</groupId> 
    <artifactId>maven-javadoc-plugin</artifactId> 
    <configuration> 
     <links> 
      <link>http://java.sun.com/j2se/1.5.0/docs/api/</link> 
     </links> 
     <source>1.5</source> 
     <show>public</show> 
     <doctitle>Foo API</doctitle> 
     <title>Foo API</title> 
     <bottom><![CDATA[Copyright notice]]></bottom> 
     <sourcepath>${basedir}/src/main/java/com/foo/api;${basedir}/src/main/java/com/bar/api</sourcepath> 
    </configuration> 
</plugin> 

Sin embargo, esto es esencialmente una solución y estoy totalmente de acuerdo con el comentario de shek que este debe ser un Enchancement contra el experto-javadoc-plugin, ya que se apoya en la utilidad javadoc. http://jira.codehaus.org/browse/MJAVADOC

Answer 2

Por lo que sé, solo se puede filtrar a nivel de paquete. Sin embargo, Javadoc solo se genera para tipos públicos y protegidos. Si los tipos tienen un alcance predeterminado o privado, no tendrán generado javadoc para ellos. Hacerlos con un alcance predeterminado significa que todavía son visibles para otros tipos en el paquete. Si no quieres javadoc, probablemente no quieras que las personas usen esos tipos, por lo que este es probablemente un buen alcance para todos.

La configuración excludePackageNames permite comodines. Por lo tanto, siempre que tenga una convención de nombre de paquete que lo permita, puede excluir la mayoría de los paquetes.

Digamos que tiene estos paquetes.

com.foo 
com.foo.api 
com.foo.internal 
com.foo.internal.core 
com.foo.internal.util 
com.foo.internal.ui 
com.foo.ui 

y sólo desea exponer foo, foo.api y foo.ui, este patrón funciona:

<excludePackageNames>com.foo.internal.*:com.foo.bob</excludePackageNames> 

Se podía mover alternativamente los tipos infractores en paquetes separados, pero esto no es una buena razón para hacerlo.

¿Cuál es el problema con la generación de javadoc para estos tipos?

Answer 3

Usando el maven-javadoc-plugin, no puede especificar clases de java específicas (aunque puede hacerlo con la utilidad javadoc, vea a continuación). Sin embargo, a través de la opción de configuración sourcepath para el objetivo javadoc: javadoc, puede configurar paquetes específicos. Un ejemplo de esto sigue:

<plugin> 
    <groupId>org.apache.maven.plugins</groupId> 
    <artifactId>maven-javadoc-plugin</artifactId> 
    <version>2.5</version> 
    <configuration> 
     <charset>UTF-8</charset> 
     <docencoding>UTF-8</docencoding> 
     <docfilessubdirs>true</docfilessubdirs> 
     <links> 
      <link>http://java.sun.com/j2se/1.5.0/docs/api/</link> 
     </links> 
     <show>protected</show> 
     <source>1.5</source> 
     <sourcepath>${basedir}/src/main/java/com/acme/foo</sourcepath> 
    </configuration> 
    <reportSets> 
     <reportSet> 
      <reports> 
       <report>javadoc</report> 
      </reports> 
     </reportSet> 
    </reportSets> 
</plugin> 

En este ejemplo, todas las clases en el marco del com.acme.foo paquete (incluyendo subpaquetes) tendrán Javadoc generado.

Cabe señalar que este plugin de Maven es simplemente una envoltura alrededor de Sun's javadoc utility. Como tal, la mayor parte de la documentación y configuración para javadoc se cumple para este complemento. Consulte la documentación de Sun en javadoc sourcepath parameter.

En un área donde el plugin maven-javadoc-plugin difiere en funcionalidad, la documentación de Sun para el parámetro sourcepath menciona que es posible con la utilidad javadoc a generate javadoc for specific classes. Esta capacidad no está disponible con el maven-javadoc-plugin. Un ejemplo de esto se muestra en la documentación del sol:

C:> cd C:\home\src\java\awt 
    C:> javadoc -d C:\home\html Button.java Canvas.java Graphics*.java 

Answer 4

Es simplemente, cuando se utiliza la etiqueta de configuración <subpackages/> de Maven2-Plugin, por ejemplo:

<plugin> 
    <groupId>org.apache.maven.plugins</groupId> 
    <artifactId>maven-javadoc-plugin</artifactId> 
    <version>2.7</version> 
    <configuration> 
     <sourceEncoding>ISO-8859-1</sourceEncoding> 
     <quiet>true</quiet> 
     <aggregate>true</aggregate> 
     <code>javadoc:aggregate</code> 
     <code>javadoc:test-aggregate</code>   
     <doclet>gr.spinellis.umlgraph.doclet.UmlGraphDoc</doclet> 
     <docletArtifact> 
      <groupId>gr.spinellis</groupId> 
      <artifactId>UmlGraph</artifactId> 
      <version>4.6</version> 
     </docletArtifact> 
     <additionalparam> 
      -inferrel -inferdep -quiet -hide java.* 
      -collpackages java.util.* -qualify 
      -postfixpackage -nodefontsize 9 
      -nodefontpackagesize 7       
     </additionalparam> 

     <subpackages> 
      de.interforum.gms.db.domain:de.interforum.sdr.db.domain 
     </subpackages> 

    </configuration> 
    <executions> 
     <execution> 
     <goals> 
      <goal>javadoc</goal> 
      <goal>test-javadoc</goal> 
     </goals> 
     <phase>site</phase> 
     <configuration> 
      <!-- Specific configuration for the given reports ... --> 
     </configuration> 
     </execution> 
    </executions> 
</plugin> 

Answer 5

Desde experto-javadoc-plugin versión 2.9, se puede hacer esto en su configuración:

<plugin> 
    <groupId>org.apache.maven.plugins</groupId> 
    <artifactId>maven-javadoc-plugin</artifactId> 
    <version>2.9</version> 
    <configuration> 
    .... 
    <sourceFileIncludes> 
     <include>Foo.java</include> 
     <include>Bar.java</include> 
    </sourceFileIncludes> 
    <sourcepath>${basedir}/src/main/java/path/to/foo-and-bar</sourcepath> 
    .... 
    </configuration> 
    .... 

... que construiría un sitio Javadoc que solo incluyera las clases mencionadas.