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.,