Maven: Dependency-driven javadoc aggregation and custom doclet

问题

I've prepared a very simple demo of what I would like to do in much bigger scale to demonstrate the issue:

Configuration: java 1.8, maven 3.3.9, maven-javadoc-plugin 3.0.1

I've got maven artifacts testA, testB and testC. Component testA is a javadoc aggregator project. Class B (located in testB component) imports and instantiates class C (located in testC component).

testA has a direct dependency on testB and testB has direct dependency on testC (both with scope provided), thus testA has transitive dependency on testC.

In addition, class B is tagged with a custom javadoc tag.

As I have no experience with writing doclets, I used a doclet I found on the internet and modified it to my needs (basically I just rewrote exclude method to include only class docs containing the custom tag).

As mentioned above, testA is an aggregator, which is intended to gather dependency sources from direct (non-transitive) dependencies only and generate javadoc for tagged classes only. This requires any direct dependencies to bundle their source codes during the build, so I use maven-source-plugin to generate source artifact from component testB.

Now, the problem is, when I run maven javadoc plugin, it fails on this exception:

[ERROR] java.lang.ArrayIndexOutOfBoundsException: 0
[ERROR] at com.sun.tools.doclets.formats.html.ConfigurationImpl.setTopFile(ConfigurationImpl.java:537)

The exception refers to this line:

this.topFile = DocPath.forPackage(this.packages[0]).resolve(DocPaths.PACKAGE_SUMMARY);

It seems like there is no package to be processed. However I am sure the doclet works as intended when executed on a single component (non-aggregation usage, tried without maven - javadoc cmd). Also the whole aggregation thing works when I use the Standard doclet, but that's not of use for me as I really need to include only the tagged classes.

Here is my aggregator's POM.xml:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>test</groupId>
  <artifactId>testA</artifactId>
  <version>1</version>

  <dependencies>

    <dependency>
        <groupId>com.sun</groupId>
        <artifactId>tools</artifactId>
        <version>1.8</version>
        <scope>system</scope>
        <systemPath>${java.home}/../lib/tools.jar</systemPath>
    </dependency>

    <dependency>
        <groupId>test</groupId>
        <artifactId>testB</artifactId>
        <version>1</version>
        <scope>provided</scope>
    </dependency>

  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>3.0.1</version>
        <configuration>

          <destDir>testOutput</destDir>
          <includeDependencySources>true</includeDependencySources>
          <doclet>com.test.MyDoclet</doclet>

          <docletArtifact>
            <groupId>test</groupId>
            <artifactId>my-doclet-artifact</artifactId>
            <version>1</version>
          </docletArtifact>

          <useStandardDocletOptions>true</useStandardDocletOptions>

          <tags>
            <tag>
              <name>MyTag</name>
            </tag>
          </tags>

        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

What am I doing wrong? Could someone help me, please?

回答1:

Actually, I managed to make it work. Problem was with the doclet code. I didn't know how the javadoc processes the code elements.

There is a tree structure starting with RootDoc node. From there it walks this tree down. RootDoc -> packages -> classes -> members etc. Since I processed tagged classes only, everything else was skipped. Thus recursion was broken right at the beginning - none of the PackageDoc elements passed the condition, so nothing was processed in the end.

I can store (include) whatever I want for the javadoc, but I have to ensure recursion continues no matter what type of element is processed.

来源：https://stackoverflow.com/questions/52443363/maven-dependency-driven-javadoc-aggregation-and-custom-doclet

标签

java

maven

javadoc

maven-javadoc-plugin

doclet