[jdk17] RFR: JDK-8262886: javadoc generates broken links with {@inheritDoc}

Jonathan Gibbons jjg at openjdk.java.net
Wed Jun 30 16:20:07 UTC 2021


On Fri, 11 Jun 2021 07:14:42 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

> (This jdk17 PR is the continuation of PR openjdk/jdk#4459 in the mainline jdk repo, commits are identical at the point of transition.)
> 
> This change fixes a whole slew of shortcomings in the redirection of relative links in doc comments. The basic idea is that relative links are authored to work in their "native primary"  environment (e.g. the package summary page for a package or the class page for a class and its members), and have to be rewritten when used in other contexts such as "use" or index pages.
> 
> A list of omissions that are fixed in this change:
> 
>  - Relative links in class or member comments were not redirected when inherited by other classes
>  - Relative links in package comments were not rewritten when displayed in other package summaries as "related packages"
>  - Fragment links used in foreign contexts were not completed with the file name
>  - Relative links in module comments were not redirected at all
> 
> While fixing above issues I also made sure link rewriting is kept to a minimum, avoiding it as much as possible for elements that live in the same package.
> 
> Furthermore, the test for redirected relative links was a bit out of order. The `javadoc` command issued by the test returned `ERROR` because one of the source files contained non-valid HTML (an anchor with a `name` attribute to test whether that attribute would be modified). Because of this, the `checkLinks()` method was never invoked, which is a problem for a test that is supposed to make sure generated links are valid. I changed the test to use the valid `id` attribute instead of `name` and made sure `checkLinks()` is executed again.
> 
> I also added checks for the newly supported cases. I added a whole new test for modules since retrofitting the existing test to cover modules would not have been practical.

(general wishful thinking)
It would be nice to move the "relative links" code out of `HtmlDocletWriter` into another class more focussed on link handling.  `HtmlDocletWriter` (and its historical supertypes, now eliminated) has always been a bit of a _utils_ or _misc_ dumping ground and it would be good to continue improving the abstractions in this area.

-------------

PR: https://git.openjdk.java.net/jdk17/pull/17


More information about the javadoc-dev mailing list