RFR: 8356975: Provide alternative way to generate preview API docs [v2]

[Andrey Turbanov]

On Tue, 15 Jul 2025 11:04:05 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

>> Please review a change to allow marking API elements as preview features via a new hidden `--preview-feature-tag` option. In conjunction with the already existing hidden `--preview-note-tag` option this allows documenting elements as preview features without relying on JDK-internal types. 
>> 
>> Part of this change is a refactoring of how `SummaryListWriter` allows its subclasses to extend the content of summary pages. The old `addExtra*` hook methods were too unflexible as they always add extra content before other page content. I replaced them with protected `getIndexLinks` and `addSummaries` methods that allow overriding methods to add extra content before or after the default content returned by the super method.
>> 
>> The change also includes the fix for [JDK-8355933](https://bugs.openjdk.org/browse/JDK-8355933) to change the presentation and wording for elements with preview notes as requested by the Valhalla team. 
>> 
>> The output generated by the new test with preview features marked by tags [can be viewed here](https://cr.openjdk.org/~hannesw/8356975/out.00/api/package-summary.html).
>
> Hannes Wallnöfer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Add warning for multiple preview notes

test/langtools/jdk/javadoc/doclet/testPreviewTag/TestPreviewTag.java line 38:

> 36: import javadoc.tester.JavadocTester;
> 37: 
> 38: public class TestPreviewTag  extends JavadocTester {

Suggestion:

public class TestPreviewTag extends JavadocTester {

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

PR Review Comment: https://git.openjdk.org/jdk/pull/26267#discussion_r2210631534