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

[Jonathan Gibbons]

On Tue, 25 Oct 2022 13:54:54 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:
> 
>   Add reference parsing modes and doctree tests

Thanks for the new support in the doc-comment-parser for kinds of references. While docent may be able to make better checks, it can also be disabled, so it is good to catch things early where that is possible.

I noticed various additional new/improved doc comments as well: nice!

test/langtools/jdk/javadoc/doclet/testSeeLinkAnchor/TestSeeLinkAnchor.java line 114:

> 112:         checkOrder("m1/module-summary.html",
> 113:             """
> 114:                     <a href="../m2/com/m2/Class2.html#main-heading"><code>See main heading in Class2</code></a>""");

It seems like an anti-pattern to check the order of a single item!
Is this as intended?  Other examples, below, provide pairs.

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

Marked as reviewed by jjg (Reviewer).

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