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
(repeating? after first message was lost...?)
I primarily reviewed the `DocCommentParser` level of the code.
Removing the `allowMember` parameter from the `reference` method seems like a
retrograde step, since there are places where the method is called that require
a specific kind of reference, such as requiring a type name after `@throws`.
If anything you should honor the `TODO` that you deleted there, and upgrade the
`boolean allowMember` parameter into some sort of enum set that allows a caller
to specify the kinds of reference that are acceptable in any given syntactic
position. After all, the new `##` syntax should only be permitted in `@see`
and `{@link}` nodes.
-------------
PR: https://git.openjdk.org/jdk/pull/10395
