On Mon, 17 Oct 2022 15:03:12 GMT, Hannes Wallnöfer <hann...@openjdk.org> wrote:
>> 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: > > Remove remaining references to aux doc link support The `allowMember` parameter was never used, so this doesn't change existing behaviour. The validity of `@throws` references is checked by doclint, where we have much more context (such as whether a type is throwable). We could enforce restrictions on references at the parser level, but it will affect code down the line such as the doclint `@throws` checks. ------------- PR: https://git.openjdk.org/jdk/pull/10395
