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

[Jonathan Gibbons]

On Fri, 7 Oct 2022 13:51:23 GMT, Hannes Wallnöfer <hannesw at 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 aux doc file reference feature

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 417:

> 415:     // TODO: improve quality of parse to forbid bad constructions.
> 416:     @SuppressWarnings("fallthrough")
> 417:     protected DCReference reference(boolean allowMember) throws ParseException {

Why has this been removed?

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 1234:

> 1232:                 public DCTree parse(int pos) throws ParseException {
> 1233:                     skipWhitespace();
> 1234:                     DCReference ref = reference();

You seem to be opening up the possibility that `@throws` can be followed by a member, which is a regression.

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/ReferenceParser.java line 118:

> 116:                 // A slash following a hash is part of a doc-file path, not a module separator
> 117:                 slash = -1;
> 118:             }

I thought we were backing off file references ...

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/TagletWriterImpl.java line 490:

> 488:         } else if (refFragment != null && refFragment.startsWith("#")) {
> 489:             if (labelContent.isEmpty()) {
> 490:                 // A non-empty label is required for fragment and auxiliary file links

"auxiliary file links" ...

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

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