JDK-8262886: javadoc generates broken links with {@inheritDoc}

[hns]

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.

---

Progress

• Change must not contain extraneous whitespace
• Commit message must refer to an issue
• Change must be properly reviewed

Issue

• JDK-8262886: javadoc generates broken links with {@inheritdoc}

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.java.net/jdk pull/4459/head:pull/4459
$ git checkout pull/4459

Update a local copy of the PR:
$ git checkout pull/4459
$ git pull https://git.openjdk.java.net/jdk pull/4459/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 4459

View PR using the GUI difftool:
$ git pr show -t 4459

Using diff file

Download this PR as a diff file:
https://git.openjdk.java.net/jdk/pull/4459.diff

[bridgekeeper]

👋 Welcome back hannesw! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

[openjdk]

@hns The following label will be automatically applied to this pull request:

• javadoc

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing list. If you would like to change these labels, use the /label pull request command.

[mlbridge]

Webrevs

• 01: Full - Incremental (0a597560)
• 00: Full (89945cce)

[pavelrappo]

If you haven't already, please run doccheck on the JDK API documentation to make sure the issues mentioned in the JBS issue are gone.

[hns]

If you haven't already, please run doccheck on the JDK API documentation to make sure the issues mentioned in the JBS issue are gone.

I have checked the mentioned issues. The ones in MemoryAddress were actual documentation errors which have been fixed in the meantime. The others are solved by this change.

[hns]

This PR is succeeded by openjdk/jdk17#17.