Maven javadoc плъгин - как мога да включа само определени класове?

От maven-javadoc-plugin версия 2.9 можете да направите това във вашата конфигурация:

<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>
  ....

... което би изградило сайт на Javadoc, включващ само споменатите класове.

С помощта на maven-javadoc-plugin не можете да посочите конкретни класове на Java ( въпреки че можете с помощната програма javadoc, вижте по-долу). Въпреки това, чрез опцията за конфигуриране sourcepath за целта javadoc:javadoc можете да конфигурирате конкретни пакети. Следва пример за това:

<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>

В този пример всички класове под пакета com.acme.foo (включително подпакети) ще имат генериран javadoc.

Трябва да се отбележи, че този плъгин на Maven е просто обвивка около Помощна програма javadoc на Sun. Като такава, по-голямата част от документацията и конфигурацията за javadoc важи за този плъгин. Вижте документацията на Sun за параметъра sourcepath.

В област, където maven-javadoc-plugin се различава по функционалност, документацията на Sun за параметъра sourcepath споменава, че е възможно с помощната програма javadoc да генерирайте javadoc за конкретни класове. Тази възможност не е налична с приставката maven-javadoc-plugin. Пример за това е показан в документацията на Sun:

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

Това е просто, когато използвате конфигурационния таг <subpackages/> от Maven2-Plugin, напр.:

    <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>

В крайна сметка използвах опцията за конфигуриране sourcepath, за да укажа два пакета, съдържащи класовете, които исках за Javadoc, и дадох класове в тези пакети, които не исках за достъп по подразбиране за Javadoc. Задаването на опцията за конфигуриране show на публична ми позволи да избера за кои класове се произвежда Javadoc, като зададох публичен достъп. Пълна конфигурация по-долу:

<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>

Това обаче по същество е заобиколно решение и аз съм напълно съгласен с коментара на shek, че това трябва да е подобрение срещу maven-javadoc-plugin, тъй като се поддържа от помощната програма за javadoc. http://jira.codehaus.org/browse/MJAVADOC

Доколкото знам, можете да филтрирате само на ниво пакет. Javadoc обаче се генерира само за публични и защитени типове. Ако типовете са с обхват по подразбиране или частни, те няма да имат генериран javadoc за тях. Ако ги направите с обхват по подразбиране, те все още са видими за други типове в пакета. Ако не искате javadoc, вероятно не искате хората да използват тези типове, така че това вероятно е добър обхват, за който да отидете така или иначе.

Конфигурацията excludePackageNames позволява заместващи знаци. Така че, докато имате конвенция за имена на пакети, която позволява това, можете да изключите повечето пакети.

Кажете, че имате тези пакети.

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

и искате да изложите само foo, foo.api и foo.ui, този модел ще работи:

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

Можете алтернативно да преместите типовете нарушители в отделни пакети, но това не е добра причина да го правите.

Какъв е проблемът с генерирането на javadoc за тези типове?