Generating Javadoc in a Maven project using <detectLinks> does not work

[alerosmile]

The maven-javadoc-plugin has an option detectLinks which enables detection of Javadoc links of dependent projects. The detection works only if the dependent project follows the default Maven conventions (javadoc must be located under ${project.url}/apidocs).

The project URL of assertj-core is https://assertj.github.io/doc/#assertj-core. The Maven plugin first checks if the URL https://assertj.github.io/doc/#assertj-core/apidocs/element-list is accessible and then forwards the URL 'https://assertj.github.io/doc/#assertj-core/apidocs' to the javadoc tool.

But the javadoc tool interprets the # character, reads the URL https://assertj.github.io/doc/package-list and obviously fails:

Error fetching URL: https://assertj.github.io/doc/#assertj-core/apidocs/ (java.io.FileNotFoundException: https://assertj.github.io/doc/package-list)

I can workaround this by defining in my project:

  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <configuration>
      <dependencyLinks>
        <dependencyLink>
          <groupId>org.assertj</groupId>
          <artifactId>assertj-core</artifactId>
          <url>https://www.javadoc.io/doc/org.assertj/assertj-core/${assertj.version}</url>
        </dependencyLink>
      </dependencyLinks>
    </configuration>
  </plugin>

Maybe the project URL of assertj-core should be https://www.javadoc.io/doc/org.assertj/assertj-core/${assertj.version} instead of https://assertj.github.io/doc/#assertj-core. But then the javadoc must be located under https://www.javadoc.io/doc/org.assertj/assertj-core/${assertj.version}/apidocs.

[scordio]

Maybe the project URL of assertj-core should be https://www.javadoc.io/doc/org.assertj/assertj-core/${assertj.version} instead of https://assertj.github.io/doc/#assertj-core. But then the javadoc must be located under https://www.javadoc.io/doc/org.assertj/assertj-core/${assertj.version}/apidocs.

I wouldn't point the project URL to javadoc.io. However, I see the problem.

We might deploy the Javadoc following the {project.url}/apidocs convention, where project.url would still belong to assertj.github.io.

However, I checked how some other projects behave and none of them seems to follow the Maven convention:

• JUnit: expected vs. actual
• Mockito: expected vs. actual
• Spring Framework: expected vs. actual

[alerosmile]

@scordio You are right. Many other projects do not follow the convention, but none of them has broken my build so far.

In other projects, the Maven plugin detects the 'invalid' links and doesn't forward them to the javadoc tool. Maybe the Maven plugin should interpret the # character the same way the javadoc plugin does.

Currently, my workaround seems to be the way to go.

[scordio]

We will rework our docs to support v3 and v4 in parallel (and maybe relocate them somewhere else in our GitHub org) so I'm leaving this open for further thoughts.

[scordio]

Just FYI, we use a slightly shorter config in assertj-guava:

assertj/assertj-guava/pom.xml

Lines 168 to 171 in 4f072c9

	<links>
	<link>https://javadoc.io/doc/com.google.guava/guava/${guava.version}</link>
	<link>https://javadoc.io/doc/org.assertj/assertj-core/${project.version}</link>
	</links>

And I just realized we have a cosmetic bug 🙂 (#3478)

[alerosmile]

You have to use <dependencyLinks> if <detectLinks> is enabled.

The <links> option just adds additional links.