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.

[michael-o]

It is not clear to me the expectation is. Both https://assertj.github.io/doc/#assertj-core/apidocs/package-list and https://assertj.github.io/doc/package-list point to non-existing resources. Please explain?

[alerosmile]

@michael-o Not sure what you mean. For me, both URLs are accessible. But the URL including the # are is interpreted differently by the javadoc tool (see my first post).

[michael-o]

@michael-o Not sure what you mean. For me, both URLs are accessible. But the URL including the # are is interpreted differently by the javadoc tool (see my first post).

I need to correct myself: Both resources point to existing, but invalid resources:

mosipov@mikaw10 MINGW64 ~
$ curl 'https://assertj.github.io/doc/#assertj-core/apidocs/package-list' | head
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  1  926k    1 16375    0     0   227k      0  0:00:04 --:--:--  0:00:04  228k<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 2.0.10">
<link rel="icon" type="image/png" href="./images/favicon.png">
<title>AssertJ - fluent assertions java library</title>
<style>
  3  926k    3 32750    0     0   428k      0  0:00:02 --:--:--  0:00:02  432k
curl: (23) Failure writing output to destination

mosipov@mikaw10 MINGW64 ~
$ curl 'https://assertj.github.io/doc/package-list' | head
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="Content-type" content="text/html; charset=utf-8">
    <meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'; img-src data:; connect-src 'self'">
    <title>Page not found &middot; GitHub Pages</title>
    <style type="text/css" media="screen">
      body {
        background-color: #f1f1f1;
        margin: 0;
 97  9379   97  9173    0     0  62047      0 --:--:-- --:--:-- --:--:-- 61979
curl: (23) Failure writing output to destination

Neither a fixed Maven Javadoc Plugin nor Javadoc itself can use it...

[alerosmile]

Whether the resources are valid or not is not the point in this case.

It is important that the Maven plugin and the Javadoc tool interpret the URL identically. The Maven plugin checks whether the URL is accessible. If yes, the URL is added to the options file for the Javadoc tool.

In this case the Maven plugin checks the URL https://assertj.github.io/doc/#assertj-core/apidocs/element-list. It is accessible and therefore added to the options file. But the Javadoc tool does not access the same URL, it tries to read https://assertj.github.io/doc/package-list which is not accessible and therefore the Javadoc tool fails.

In order to not fail the build, only URLs which are accessible by the Javadoc tool should be added to the options file. For this to work properly, the Maven plugin must interpret the URLs exactly the same way the Javadoc tool does.

[michael-o]

Whether the resources are valid or not is not the point in this case.

It is important that the Maven plugin and the Javadoc tool interpret the URL identically. The Maven plugin checks whether the URL is accessible. If yes, the URL is added to the options file for the Javadoc tool.

In this case the Maven plugin checks the URL https://assertj.github.io/doc/#assertj-core/apidocs/element-list. It is accessible and therefore added to the options file. But the Javadoc tool does not access the same URL, it tries to read https://assertj.github.io/doc/package-list which is not accessible and therefore the Javadoc tool fails.

In order to not fail the build, only URLs which are accessible by the Javadoc tool should be added to the options file. For this to work properly, the Maven plugin must interpret the URLs exactly the same way the Javadoc tool does.

Agreed, or the plugin should not check the resource at all and leave everything to Javadoc. At the end, no one needs duplicate checks w/o any benefits. PRs welcome.

[michael-o]

What I can offer is to broaden the validation scope of the validateLinks paramater not to touch URLs at all, instead of getting them and not validating content... maybe that would be most reasonable. Why fetch if you don't check the content. It can be deceiving.

[alerosmile]

I think the reason why this has been done this way is to not break the build on invalid links. If the javadoc tool cannot read the URL it fails. If it fails, the Maven plugin fails the build.

[michael-o]

I think the reason why this has been done this way is to not break the build on invalid links. If the javadoc tool cannot read the URL it fails. If it fails, the Maven plugin fails the build.

No objections here, but to be honest one would need to replicate the logic of every Javadoc version to do the verification as the Java version being used. If Javadoc considers it as invalid it should either fail or warn. That is why validateLinks should be off by default, and it is.