RFR: JDK-6251738: Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec) [v14]

[Hannes Wallnöfer]

On Thu, 22 Sep 2022 03:41:23 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review the code and tests to add support for a new `@spec url title` tag to javadoc.  Note, this does not include any changes to API doc comments to use the new tag in JDK API documentation; that will come later.
>
> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 22 commits:
> 
>  - Fix merge issue
>  - Merge remote-tracking branch 'upstream/master' into 6251738.spec-tag-2
>  - Merge with upstream/master
>  - Fix typo and merge error
>  - Merge with upstream/master
>  - Update @since tags
>  - Merge remote-tracking branch 'upstream/master' into 6251738.spec-tag-2
>  - Merge remote-tracking branch 'upstream/master' into 6251738.spec-tag-2
>  - Updates for latest repo
>  - Merge remote-tracking branch 'upstream/master' into 6251738.spec-tag-2
>  - ... and 12 more: https://git.openjdk.org/jdk/compare/2283c324...be7510e5

All looks very good! The only place that looks suspicious to me is the `inherit` implementation in `SpecTaglet.java`, which also seems not to be covered by the test. 

I guess the best way to examine the output of the new tag is via test output. I'll have a look at that to see the HTML and CSS in action before giving a thumbs up.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SpecTaglet.java line 65:

> 63:                     ? ch.getFirstSentenceTrees(output.holderTag)
> 64:                     : ch.getReference(output.holderTag);
> 65:         }

This implementation seems to be copied from SeeTaglet.java. Is it fully functional in this context? The use of CommentHelper.getReference looks suspicious to me.

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

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