On Fri, 7 Oct 2022 13:51:23 GMT, Hannes Wallnöfer <[email protected]> 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
