From a5d0b05136e34871366441a8c8e6bda5f20c617c Mon Sep 17 00:00:00 2001 From: Chen Liang Date: Tue, 27 Jan 2026 15:04:26 +0000 Subject: [PATCH] 8376274: JSpec preview support and output enhancement Reviewed-by: hannesw --- .../src/classes/build/tools/taglet/JSpec.java | 69 ++++++++++++++++--- .../lang/runtime/ExactConversionsSupport.java | 11 ++- 2 files changed, 62 insertions(+), 18 deletions(-) diff --git a/make/jdk/src/classes/build/tools/taglet/JSpec.java b/make/jdk/src/classes/build/tools/taglet/JSpec.java index 1c301e94a8a..7e1e0ca215e 100644 --- a/make/jdk/src/classes/build/tools/taglet/JSpec.java +++ b/make/jdk/src/classes/build/tools/taglet/JSpec.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2017, 2025, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2017, 2026, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -49,13 +49,15 @@ import static com.sun.source.doctree.DocTree.Kind.*; * The tags can be used as follows: * * 
- * @jls section-number description
+ * @jls chapter.section description
+ * @jls preview-feature-chapter.section description
  *
* * For example: * * 
  * @jls 3.4 Line Terminators
+ * @jls primitive-types-in-patterns-instanceof-switch-5.7.1 Exact Testing Conversions
  *
* * will produce the following HTML, depending on the file containing @@ -64,10 +66,24 @@ import static com.sun.source.doctree.DocTree.Kind.*; * 
{@code
  * 
See Java Language Specification:
  * 
3.4 Line terminators
+ * 

+ * 5.7.1 Exact Testing Conversions
+ * PREVIEW
  * }
* - * Copies of JLS and JVMS are expected to have been placed in the {@code specs} - * folder. These documents are not included in open-source repositories. + * In inline tags (note you need manual JLS/JVMS prefix): + * 
+ * JLS {@jls 3.4}
+ *
+ * + * produces (note the section sign and no trailing dot): + * 
+ * JLS §3.4
+ *
+ * + * Copies of JLS, JVMS, and preview JLS and JVMS changes are expected to have + * been placed in the {@code specs} folder. These documents are not included + * in open-source repositories. */ public class JSpec implements Taglet { @@ -87,9 +103,9 @@ public class JSpec implements Taglet { } } - private String tagName; - private String specTitle; - private String idPrefix; + private final String tagName; + private final String specTitle; + private final String idPrefix; JSpec(String tagName, String specTitle, String idPrefix) { this.tagName = tagName; @@ -98,7 +114,7 @@ public class JSpec implements Taglet { } // Note: Matches special cases like @jvms 6.5.checkcast - private static final Pattern TAG_PATTERN = Pattern.compile("(?s)(.+ )?(?[1-9][0-9]*)(?
[0-9a-z_.]*)( .*)?$"); + private static final Pattern TAG_PATTERN = Pattern.compile("(?s)(.+ )?(?([a-z0-9]+-)+)?(?[1-9][0-9]*)(?
[0-9a-z_.]*)( .*)?$"); /** * Returns the set of locations in which the tag may be used. @@ -157,19 +173,50 @@ public class JSpec implements Taglet { .trim(); Matcher m = TAG_PATTERN.matcher(tagText); if (m.find()) { + // preview-feature-4.6 is preview-feature-, 4, .6 + String preview = m.group("preview"); // null if no preview feature String chapter = m.group("chapter"); String section = m.group("section"); String rootParent = currentPath().replaceAll("[^/]+", ".."); - String url = String.format("%1$s/specs/%2$s/%2$s-%3$s.html#%2$s-%3$s%4$s", - rootParent, idPrefix, chapter, section); + String url = preview == null ? + String.format("%1$s/specs/%2$s/%2$s-%3$s.html#%2$s-%3$s%4$s", + rootParent, idPrefix, chapter, section) : + String.format("%1$s/specs/%5$s%2$s.html#%2$s-%3$s%4$s", + rootParent, idPrefix, chapter, section, preview); + + var literal = expand(contents).trim(); + var prefix = (preview == null ? "" : preview) + chapter + section; + if (literal.startsWith(prefix)) { + var hasFullTitle = literal.length() > prefix.length(); + if (hasFullTitle) { + // Drop the preview identifier + literal = chapter + section + literal.substring(prefix.length()); + } else { + // No section sign if the tag refers to a chapter, like {@jvms 4} + String sectionSign = section.isEmpty() ? "" : "§"; + // Change whole text to "§chapter.x" in inline tags. + literal = sectionSign + chapter + section; + } + } sb.append("") - .append(expand(contents)) + .append(literal) .append(""); + if (preview != null) { + // Add PREVIEW superscript that links to JLS/JVMS 1.5.1 + // "Restrictions on the Use of Preview Features" + // Similar to how APIs link to the Preview info box warning + var sectionLink = String.format("%1$s/specs/%2$s/%2$s-%3$s.html#%2$s-%3$s%4$s", + rootParent, idPrefix, "1", ".5.1"); + sb.append("PREVIEW"); + } + if (tag.getKind() == DocTree.Kind.UNKNOWN_BLOCK_TAG) { sb.append("
"); } diff --git a/src/java.base/share/classes/java/lang/runtime/ExactConversionsSupport.java b/src/java.base/share/classes/java/lang/runtime/ExactConversionsSupport.java index a1a93859c42..8d4389f7295 100644 --- a/src/java.base/share/classes/java/lang/runtime/ExactConversionsSupport.java +++ b/src/java.base/share/classes/java/lang/runtime/ExactConversionsSupport.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2024, 2025, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2024, 2026, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -64,12 +64,9 @@ package java.lang.runtime; * floating-point type is considered exact. * * - * @see - * JLS 5.7.1 Exact Testing Conversions - * @see - * JLS 5.7.2 Unconditionally Exact Testing Conversions - * @see - * JLS 15.20.2 The instanceof Operator + * @jls primitive-types-in-patterns-instanceof-switch-5.7.1 Exact Testing Conversions + * @jls primitive-types-in-patterns-instanceof-switch-5.7.2 Unconditionally Exact Testing Conversions + * @jls primitive-types-in-patterns-instanceof-switch-15.20.2 The {@code instanceof} Operator * * @implNote Some exactness checks describe a test which can be redirected * safely through one of the existing methods. Those are omitted too (i.e.,