Javadoc 1.8 cannot link to the published 1.1.0 API documentation

sdavids commented 4 years ago

Javadoc 1.8 cannot link to the documentation published at https://apiguardian-team.github.io/apiguardian/docs/1.1.0/api/.

build.gradle

plugins {
  id 'java-library'
}

sourceCompatibility = JavaVersion.VERSION_1_8

repositories.mavenCentral()

ext.apiGuardianVersion = '1.1.0'

dependencies {
  api "org.apiguardian:apiguardian-api:${apiGuardianVersion}"
}

tasks.named('javadoc').configure {
  options.links = [
      'https://docs.oracle.com/javase/8/docs/api/',
      "https://apiguardian-team.github.io/apiguardian/docs/${apiGuardianVersion}/api/"
  ] as String[]
}

src/main/java/Test.java

import org.apiguardian.api.API;

@API(status = API.Status.EXPERIMENTAL)
public class Test {}

$ ./gradlew javadoc

> Task :javadoc
javadoc: warning - Error fetching URL: https://apiguardian-team.github.io/apiguardian/docs/1.1.0/api/
1 warning

BUILD SUCCESSFUL in 1s
2 actionable tasks: 2 executed

$ ./gradlew --version

------------------------------------------------------------
Gradle 5.2.1
------------------------------------------------------------

Build time:   2019-02-08 19:00:10 UTC
Revision:     f02764e074c32ee8851a4e1877dd1fea8ffb7183

Kotlin DSL:   1.1.3
Kotlin:       1.3.20
Groovy:       2.5.4
Ant:          Apache Ant(TM) version 1.9.13 compiled on July 10 2018
JVM:          1.8.0_242 (AdoptOpenJDK 25.242-b08)
OS:           Mac OS X 10.15.3 x86_64

Whereas

https://apiguardian-team.github.io/apiguardian/docs/current/api/
https://apiguardian-team.github.io/apiguardian/docs/1.0.0/api/

work.

Using Gradle 6.2.1 produces the same warning message.

sdavids commented 4 years ago

$ javadoc \
 -d doc \
 -link https://docs.oracle.com/javase/8/docs/api/ \
 -link https://apiguardian-team.github.io/apiguardian/docs/1.1.0/api/ \
 -cp ~/.m2/repository/org/apiguardian/apiguardian-api/1.1.0/apiguardian-api-1.1.0.jar \
 src/main/java/*
Loading source file src/main/java/Test.java...
Constructing Javadoc information...
javadoc: warning - Error fetching URL: https://apiguardian-team.github.io/apiguardian/docs/1.1.0/api/
Standard Doclet version 1.8.0_242
Building tree for all the packages and classes...
Generating doc/Test.html...
Generating doc/package-frame.html...
Generating doc/package-summary.html...
Generating doc/package-tree.html...
Generating doc/constant-values.html...
Building index for all the packages and classes...
Generating doc/overview-tree.html...
Generating doc/index-all.html...
Generating doc/deprecated-list.html...
Building index for all classes...
Generating doc/allclasses-frame.html...
Generating doc/allclasses-noframe.html...
Generating doc/index.html...
Generating doc/help-doc.html...
1 warning

marcphilipp commented 4 years ago

Root cause: the package-list file is missing.

sormuras commented 4 years ago

Here's a collection of related javadoc issues:

Some/all will be fixed with JDK 15, I hope. Whether those potential fixes will be backported to JDK 1.8 is a different story...

apiguardian-team / apiguardian

Javadoc 1.8 cannot link to the published 1.1.0 API documentation #15