Skip to content

Reinstate links to JUnit 5 Javadoc APIs #27497

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
Closed
sbrannen opened this issue Sep 29, 2021 · 6 comments
Closed

Reinstate links to JUnit 5 Javadoc APIs #27497

sbrannen opened this issue Sep 29, 2021 · 6 comments
Assignees
@sbrannen
Labels
in: test Issues in the test module type: documentation A documentation task
Milestone
7.0.0-M4

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
@sbrannen sbrannen self-assigned this Mar 24, 2025
@sbrannen sbrannen removed this from the General Backlog milestone Mar 24, 2025
@sbrannen sbrannen added this to the 7.0.0-M4 milestone Mar 24, 2025
@sbrannen sbrannen changed the title Reinstate links to JUnit 5 Javadoc APIs using JDK 18+ Reinstate links to JUnit 5 Javadoc APIs Mar 24, 2025
@sbrannen sbrannen mentioned this issue Apr 15, 2025
Closed
@sbrannen sbrannen marked this as a duplicate of #34763 Apr 16, 2025
@sbrannen
Copy link
Member Author

Reopening to address the issue raised in #34763.

@sbrannen sbrannen reopened this Apr 16, 2025
@bclozel bclozel mentioned this issue Apr 17, 2025
Open
sbrannen added a commit that referenced this issue Apr 17, 2025
@sbrannen
Configure JDK 24 toolchain for aggregated Javadoc
49ef150 
Changes made in conjunction with #27497 now require that we generate
Javadoc with JDK 18 or higher in order to make use of the
"--link-modularity-mismatch" flag for the javadoc executable.

This commit sets the toolchain for the javadoc task in the
framework-api module to use JDK 24 for generating Javadoc.

The common javadoc task used by all spring-* modules will be addressed
in a separate commit.

See gh-27497
See gh-34774
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@sbrannen sbrannen

Labels
in: test Issues in the test module type: documentation A documentation task
Projects
None yet
Milestone
7.0.0-M4
Development

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