RFR: JDK-8200337: Generalize see and link tags for user-defined anchors [v6]

[Hannes Wallnöfer]

> Please review a a new feature to allow `@link`, `@linkplain` and `@see` tags to link to arbitrary URI fragments in the generated documentation (including in auxiliary `doc-files` documentation).
> 
> The changes in module `jdk.compiler` are mostly cleanup changes retained from earlier versions of the patch. The current proposed version uses a very simple change in `ReferenceParser` to avoid parsing the member name section of the reference when a non-member fragment is encountered.
> 
> The implementation introduces a new form of reference with a double hash mark (`##`) separator. This is a change from the previous implementation which also auto-recognized URI fragments and documentation paths by looking for `-` characters which are not allowed in member names. This feature was removed upon further consideration because it makes the feature more complex and less recognizable.
>  
> Links to auxiliary documentation files follow the same rules. They are recognized by looking for `/` characters in the fragment name. This means that ordinary `id` attribute values must not contain `/`, while auxiliary file paths must contain a `/` character. Both restrictions should be easy to sustain.
> 
> One thing that is difficult for this feature is to provide a good link label if no label is supplied in the tag. In contrast to program element names a fragment name does usually not make a good human readable name. The solution is to use the fragment name as default label text. I expect that the feature will usually be used with a user provided label.

Hannes Wallnöfer has updated the pull request incrementally with one additional commit since the last revision:

  Add reference parsing modes and doctree tests

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/10395/files
  - new: https://git.openjdk.org/jdk/pull/10395/files/1ea15afc..bfd2d7f7

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=10395&range=05
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=10395&range=04-05

  Stats: 205 lines in 10 files changed: 180 ins; 3 del; 22 mod
  Patch: https://git.openjdk.org/jdk/pull/10395.diff
  Fetch: git fetch https://git.openjdk.org/jdk pull/10395/head:pull/10395

PR: https://git.openjdk.org/jdk/pull/10395