Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Reinstate links to JUnit 5 Javadoc APIs using JDK 18+ #27497

Open
sbrannen opened this issue Sep 29, 2021 · 5 comments
Open

Reinstate links to JUnit 5 Javadoc APIs using JDK 18+ #27497

sbrannen opened this issue Sep 29, 2021 · 5 comments
Labels
in: test Issues in the test module type: documentation A documentation task
Milestone
General Backlog

Comments

@sbrannen
Copy link
Member

sbrannen commented Sep 29, 2021 •
edited
Loading

As a follow up to #27480 (see commit 030ba52), we need to determine why we cannot configure external Javadoc links to JUnit 5.

Note that code in the spring-test module (e.g., the SpringExtension for JUnit Jupiter) links to JUnit 5 APIs.

If we uncomment the following...

spring-framework/build.gradle

Lines 347 to 352 in 167e538

// TODO Uncomment link to JUnit 5 docs once we have sorted out
// the following warning in the build.
//
// warning: The code being documented uses packages in the unnamed module, but the packages defined in https://junit.org/junit5/docs/5.8.1/api/ are in named modules.
//
// "https://junit.org/junit5/docs/5.8.1/api/",

... we get the following Javadoc warning which fails the build.

warning: The code being documented uses packages in the unnamed module, but the packages defined in https://junit.org/junit5/docs/5.8.1/api/ are in named modules.

Related JDK issues
@sbrannen sbrannen added the type: documentation A documentation task label Sep 29, 2021
@sbrannen sbrannen added this to the 6.0 M1 milestone Sep 29, 2021
@sbrannen sbrannen self-assigned this Sep 29, 2021
@sbrannen
Copy link
Member Author

/cc @sormuras

@sbrannen
Copy link
Member Author

sbrannen commented Oct 1, 2021

Update

Thanks to a tip from @sormuras, it turns out that the links are actually generated properly in the resulting HTML if we remove the use of -Werror for the javadoc task.

Thus, the warning is merely a "warning" that we are not interested in.

Unfortunately, (as far as I know) there is currently no way to instruct javadoc not to log that as a "warning".

@sormuras
Copy link

sormuras commented Oct 1, 2021

This https://bugs.openjdk.java.net/browse/JDK-8274639 describes the underlying cause and a potential fix.

@sbrannen
Copy link
Member Author

sbrannen commented Dec 2, 2021

Java 18 will introduce a --link-modularity-mismatch option that defaults to WARN (the status quo), and we will be able to set it to INFO to prevent such warnings from breaking our build.

@sbrannen sbrannen modified the milestones: 6.0 M1, 6.0 M2 Dec 2, 2021
@sbrannen sbrannen modified the milestones: 6.0.0-M2, 6.0.0-M3 Jan 3, 2022
@sbrannen sbrannen modified the milestones: 6.0.0-M3, 6.0.0-M4, 6.0.x Mar 10, 2022
@sbrannen
Copy link
Member Author

sbrannen commented Mar 7, 2023

Java 18 will introduce a --link-modularity-mismatch option that defaults to WARN (the status quo), and we will be able to set it to INFO to prevent such warnings from breaking our build.

Spring Framework 6.0.x is built using Java 17.

Since that requires that we execute our Gradle builds with Java 18, we cannot currently address this issue.

@sbrannen sbrannen modified the milestones: 6.0.x, 6.1.x Mar 7, 2023
@sbrannen sbrannen changed the title Determine why we cannot link to JUnit 5 Javadoc APIs using JDK 17 Reinstate links to JUnit 5 Javadoc APIs using JDK 18+ Mar 7, 2023
sbrannen added a commit to sbrannen/spring-framework that referenced this issue Mar 7, 2023
@sbrannen
Update TODO for linking to JUnit 5 docs
29fe0a3 
See spring-projectsgh-27497
@sbrannen sbrannen modified the milestones: 6.1.x, 6.x Backlog Aug 19, 2023
@jhoeller jhoeller modified the milestones: 6.x Backlog, General Backlog Jan 4, 2024
@sbrannen sbrannen added the in: test Issues in the test module label Jan 16, 2024
@sbrannen sbrannen removed their assignment Jan 16, 2024
scordio added a commit to scordio/jimfs-junit-jupiter that referenced this issue Jul 29, 2024
@scordio
Fix Javadoc generation
e269a8f 
javadoc is able to create external links to libraries documented with
"mismatching" modularity, like for JUnit Jupiter, which offers modular
documentation.
However, a warning is generated when the mismatch happens, and this is
a problem when using the `-Werror` option to treat warnings as errors.

To circumvent this problem without dropping the `-Werror` option,
Java 18 added the `--link-modularity-mismatch=(warn|info)` command
line option to specify how external documentation with wrong
modularity should be reported.

See:
* https://docs.oracle.com/en/java/javase/18/docs/specs/man/javadoc.html#standard-options-for-the-standard-doclet
* https://bugs.openjdk.org/browse/JDK-8274639
* spring-projects/spring-framework#27497
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
in: test Issues in the test module type: documentation A documentation task
Projects
None yet
Milestone
General Backlog
Development

No branches or pull requests
3 participants
@sbrannen @jhoeller @sormuras