> 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 comment ------------- Changes: - all: https://git.openjdk.org/jdk/pull/10395/files - new: https://git.openjdk.org/jdk/pull/10395/files/47f85204..e0d6f5e7 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk&pr=10395&range=02 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=10395&range=01-02 Stats: 2 lines in 1 file changed: 2 ins; 0 del; 0 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
