Improving appearance of javadoc of the APIs associated with preview features.
--- a/make/jdk/src/classes/build/tools/taglet/Preview.java Wed Sep 25 21:19:21 2019 +0200
+++ b/make/jdk/src/classes/build/tools/taglet/Preview.java Wed Oct 02 10:59:40 2019 +0200
@@ -25,12 +25,14 @@
package build.tools.taglet;
+import java.util.Arrays;
import java.util.EnumSet;
import java.util.List;
import java.util.Set;
import javax.lang.model.element.Element;
import com.sun.source.doctree.DocTree;
-import com.sun.source.doctree.UnknownBlockTagTree;
+import com.sun.source.doctree.TextTree;
+import com.sun.source.doctree.UnknownInlineTagTree;
import jdk.javadoc.doclet.Taglet;
import static jdk.javadoc.doclet.Taglet.Location.*;
@@ -47,7 +49,7 @@
@Override
public boolean isInlineTag() {
- return false;
+ return true;
}
@Override
@@ -57,14 +59,16 @@
@Override
public String toString(List<? extends DocTree> tags, Element elem) {
- StringBuilder sb = new StringBuilder();
- sb.append("<dt>Preview Feature:\n");
- for (DocTree tag : tags) {
- UnknownBlockTagTree ubt = (UnknownBlockTagTree) tag;
- sb.append("<dd style=\"border: 1px solid red; border-radius: 5px; padding: 5px; font-size: larger\"> <b>Preview:</b> ")
- .append(ubt.getContent());
+ UnknownInlineTagTree previewTag = (UnknownInlineTagTree) tags.get(0);
+ List<? extends DocTree> previewContent = previewTag.getContent();
+ String previewText = ((TextTree) previewContent.get(0)).getBody();
+ String[] summaryAndDetails = previewText.split("\n\r?\n\r?");
+ String summary = summaryAndDetails[0];
+ String details = summaryAndDetails.length > 1 ? summaryAndDetails[1] : summaryAndDetails[0];
+ if (Arrays.stream(new Exception().getStackTrace()).anyMatch(el -> el.getClassName().endsWith("HtmlDocletWriter") && el.getMethodName().equals("addSummaryComment"))) {
+ return "<div style=\"display:inline-block; font-weight:bold\">" + summary + "</div><br>";
}
- return sb.toString();
+ return "<div style=\"border: 1px solid red; border-radius: 25px; padding: 5px; display:inline-block; font-size: larger\">" + details + "</div><br>";
}
}
--- a/src/java.base/share/classes/java/lang/String.java Wed Sep 25 21:19:21 2019 +0200
+++ b/src/java.base/share/classes/java/lang/String.java Wed Oct 02 10:59:40 2019 +0200
@@ -2888,6 +2888,14 @@
}
/**
+ * {@preview {@previewSummary Associated with text blocks,
+ * a preview feature of the Java language.}
+ * This method is associated with <i>text blocks</i>, a preview
+ * feature of the Java language. Programs can only use this
+ * method when preview features are enabled. Preview features
+ * may be removed in a future release, or upgraded to permanent
+ * features of the Java language.}
+ *
* Returns a string whose value is this string, with incidental
* {@linkplain Character#isWhitespace(int) white space} removed from
* the beginning and end of every line.
@@ -2963,8 +2971,6 @@
*
* @since 13
*
- * @preview This method is associated with text blocks, a preview language feature.
- * Text blocks and/or this method may be changed or removed in a future release.
*/
@jdk.internal.PreviewFeature(feature=jdk.internal.PreviewFeature.Feature.TEXT_BLOCKS,
essentialAPI=true)
@@ -3006,6 +3012,14 @@
}
/**
+ * {@preview {@previewSummary Associated with text blocks,
+ * a preview feature of the Java language.}
+ * This method is associated with <i>text blocks</i>, a preview
+ * feature of the Java language. Programs can only use this
+ * method when preview features are enabled. Preview features
+ * may be removed in a future release, or upgraded to permanent
+ * features of the Java language.}
+ *
* Returns a string whose value is this string, with escape sequences
* translated as if in a string literal.
* <p>
@@ -3080,9 +3094,6 @@
* @jls 3.10.7 Escape Sequences
*
* @since 13
- *
- * @preview This method is associated with text blocks, a preview language feature.
- * Text blocks and/or this method may be changed or removed in a future release.
*/
@jdk.internal.PreviewFeature(feature=jdk.internal.PreviewFeature.Feature.TEXT_BLOCKS,
essentialAPI=true)
@@ -3311,6 +3322,15 @@
}
/**
+ * {@preview Associated with text blocks, a preview feature of
+ * the Java language.
+ *
+ * This method is associated with <i>text blocks</i>, a preview
+ * feature of the Java language. Programs can only use this
+ * method when preview features are enabled. Preview features
+ * may be removed in a future release, or upgraded to permanent
+ * features of the Java language.}
+ *
* Formats using this string as the format string, and the supplied
* arguments.
*
@@ -3326,8 +3346,6 @@
*
* @since 13
*
- * @preview This method is associated with text blocks, a preview language feature.
- * Text blocks and/or this method may be changed or removed in a future release.
*/
@jdk.internal.PreviewFeature(feature=jdk.internal.PreviewFeature.Feature.TEXT_BLOCKS,
essentialAPI=true)
--- a/src/jdk.compiler/share/classes/com/sun/source/tree/CaseTree.java Wed Sep 25 21:19:21 2019 +0200
+++ b/src/jdk.compiler/share/classes/com/sun/source/tree/CaseTree.java Wed Oct 02 10:59:40 2019 +0200
@@ -55,6 +55,14 @@
ExpressionTree getExpression();
/**
+ * {@preview Associated with switch expressions, a preview feature of
+ * the Java language.
+ *
+ * This method is associated with <i>switch expressions</i>, a preview
+ * feature of the Java language. Preview features
+ * may be removed in a future release, or upgraded to permanent
+ * features of the Java language.}
+ *
* Returns the labels for this case.
* For default case, returns an empty list.
*
@@ -78,6 +86,14 @@
List<? extends StatementTree> getStatements();
/**
+ * {@preview Associated with switch expressions, a preview feature of
+ * the Java language.
+ *
+ * This method is associated with <i>switch expressions</i>, a preview
+ * feature of the Java language. Preview features
+ * may be removed in a future release, or upgraded to permanent
+ * features of the Java language.}
+ *
* For case with kind {@linkplain CaseKind#RULE},
* returns the statement or expression after the arrow.
* Returns {@code null} for case with kind
@@ -85,10 +101,6 @@
*
* @return case value or null
* @since 12
- *
- * @preview This method is modeling a rule case,
- * which is part of a preview feature and may be removed
- * if the preview feature is removed.
*/
@jdk.internal.PreviewFeature(feature=jdk.internal.PreviewFeature.Feature.SWITCH_EXPRESSIONS)
public default Tree getBody() {
@@ -96,14 +108,18 @@
}
/**
+ * {@preview Associated with switch expressions, a preview feature of
+ * the Java language.
+ *
+ * This method is associated with <i>switch expressions</i>, a preview
+ * feature of the Java language. Preview features
+ * may be removed in a future release, or upgraded to permanent
+ * features of the Java language.}
+ *
* Returns the kind of this case.
*
* @return the kind of this case
* @since 12
- *
- * @preview This method is used to model a rule case,
- * which is part of a preview feature and may be removed
- * if the preview feature is removed.
*/
@jdk.internal.PreviewFeature(feature=jdk.internal.PreviewFeature.Feature.SWITCH_EXPRESSIONS)
@SuppressWarnings("preview")
@@ -112,6 +128,14 @@
}
/**
+ * {@preview Associated with switch expressions, a preview feature of
+ * the Java language.
+ *
+ * This enum is associated with <i>switch expressions</i>, a preview
+ * feature of the Java language. Preview features
+ * may be removed in a future release, or upgraded to permanent
+ * features of the Java language.}
+ *
* The syntatic form of this case:
* <ul>
* <li>STATEMENT: {@code case <expression>: <statements>}</li>
@@ -119,10 +143,6 @@
* </ul>
*
* @since 12
- *
- * @preview This enum is used to model a rule case,
- * which is part of a preview feature and may be removed
- * if the preview feature is removed.
*/
@jdk.internal.PreviewFeature(feature=jdk.internal.PreviewFeature.Feature.SWITCH_EXPRESSIONS)
@SuppressWarnings("preview")
--- a/src/jdk.compiler/share/classes/com/sun/source/tree/SwitchExpressionTree.java Wed Sep 25 21:19:21 2019 +0200
+++ b/src/jdk.compiler/share/classes/com/sun/source/tree/SwitchExpressionTree.java Wed Oct 02 10:59:40 2019 +0200
@@ -28,6 +28,14 @@
import java.util.List;
/**
+ * {@preview Associated with switch expressions, a preview feature of
+ * the Java language.
+ *
+ * This interface is associated with <i>switch expressions</i>, a preview
+ * feature of the Java language. Preview features
+ * may be removed in a future release, or upgraded to permanent
+ * features of the Java language.}
+ *
* A tree node for a {@code switch} expression.
*
* For example:
@@ -40,10 +48,6 @@
* @jls 15.29 Switch Expressions
*
* @since 12
- *
- * @preview This method is modeling switch expressions,
- * which are part of a preview feature and may be removed
- * if the preview feature is removed.
*/
@jdk.internal.PreviewFeature(feature=jdk.internal.PreviewFeature.Feature.SWITCH_EXPRESSIONS)
public interface SwitchExpressionTree extends ExpressionTree {
--- a/src/jdk.compiler/share/classes/com/sun/source/tree/Tree.java Wed Sep 25 21:19:21 2019 +0200
+++ b/src/jdk.compiler/share/classes/com/sun/source/tree/Tree.java Wed Oct 02 10:59:40 2019 +0200
@@ -240,14 +240,17 @@
SWITCH(SwitchTree.class),
/**
+ * {@preview Associated with switch expressions, a preview feature of
+ * the Java language.
+ *
+ * This enum constant is associated with <i>switch expressions</i>, a preview
+ * feature of the Java language. Preview features
+ * may be removed in a future release, or upgraded to permanent
+ * features of the Java language.}
+ *
* Used for instances of {@link SwitchExpressionTree}.
*
* @since 12
- *
- * @preview
- * This enum constant is modeling switch expressions,
- * which are part of a preview feature and may be removed
- * if the preview feature is removed.
*/
@jdk.internal.PreviewFeature(feature=jdk.internal.PreviewFeature.Feature.SWITCH_EXPRESSIONS)
@SuppressWarnings("preview")
@@ -659,14 +662,17 @@
OTHER(null),
/**
+ * {@preview Associated with switch expressions, a preview feature of
+ * the Java language.
+ *
+ * This enum constant is associated with <i>switch expressions</i>, a preview
+ * feature of the Java language. Preview features
+ * may be removed in a future release, or upgraded to permanent
+ * features of the Java language.}
+ *
* Used for instances of {@link YieldTree}.
*
* @since 13
- *
- * @preview
- * This enum constant is modeling yield statement,
- * which are part of a preview feature and may be removed
- * if the preview feature is removed.
*/
@jdk.internal.PreviewFeature(feature=jdk.internal.PreviewFeature.Feature.SWITCH_EXPRESSIONS)
@SuppressWarnings("preview")
--- a/src/jdk.compiler/share/classes/com/sun/source/tree/TreeVisitor.java Wed Sep 25 21:19:21 2019 +0200
+++ b/src/jdk.compiler/share/classes/com/sun/source/tree/TreeVisitor.java Wed Oct 02 10:59:40 2019 +0200
@@ -354,17 +354,20 @@
R visitSwitch(SwitchTree node, P p);
/**
+ * {@preview Associated with switch expressions, a preview feature of
+ * the Java language.
+ *
+ * This method is associated with <i>switch expressions</i>, a preview
+ * feature of the Java language. Preview features
+ * may be removed in a future release, or upgraded to permanent
+ * features of the Java language.}
+ *
* Visits a SwitchExpressionTree node.
*
* @param node the node being visited
* @param p a parameter value
* @return a result value
* @since 12
- *
- * @preview
- * This method is modeling switch expressions,
- * which are part of a preview feature and may be removed
- * if the preview feature is removed.
*/
@jdk.internal.PreviewFeature(feature=jdk.internal.PreviewFeature.Feature.SWITCH_EXPRESSIONS)
@SuppressWarnings("preview")
@@ -557,16 +560,19 @@
R visitOther(Tree node, P p);
/**
+ * {@preview Associated with switch expressions, a preview feature of
+ * the Java language.
+ *
+ * This method is associated with <i>switch expressions</i>, a preview
+ * feature of the Java language. Preview features
+ * may be removed in a future release, or upgraded to permanent
+ * features of the Java language.}
+ *
* Visits a YieldTree node.
* @param node the node being visited
* @param p a parameter value
* @return a result value
* @since 13
- *
- * @preview
- * This method is modeling yield statement,
- * which are part of a preview feature and may be removed
- * if the preview feature is removed.
*/
@jdk.internal.PreviewFeature(feature=jdk.internal.PreviewFeature.Feature.SWITCH_EXPRESSIONS)
@SuppressWarnings("preview")
--- a/src/jdk.compiler/share/classes/com/sun/source/tree/YieldTree.java Wed Sep 25 21:19:21 2019 +0200
+++ b/src/jdk.compiler/share/classes/com/sun/source/tree/YieldTree.java Wed Oct 02 10:59:40 2019 +0200
@@ -26,6 +26,14 @@
package com.sun.source.tree;
/**
+ * {@preview Associated with switch expressions, a preview feature of
+ * the Java language.
+ *
+ * This method is associated with <i>switch expressions</i>, a preview
+ * feature of the Java language. Preview features
+ * may be removed in a future release, or upgraded to permanent
+ * features of the Java language.}
+ *
* A tree node for a {@code yield} statement.
*
* For example:
@@ -36,10 +44,6 @@
* @jls section TODO
*
* @since 13
- *
- * @preview This class is modeling yield from switch expressions,
- * which are part of a preview feature and may be removed if
- * the preview feature is removed.
*/
@jdk.internal.PreviewFeature(feature=jdk.internal.PreviewFeature.Feature.SWITCH_EXPRESSIONS)
public interface YieldTree extends StatementTree {
--- a/src/jdk.compiler/share/classes/com/sun/source/util/SimpleTreeVisitor.java Wed Sep 25 21:19:21 2019 +0200
+++ b/src/jdk.compiler/share/classes/com/sun/source/util/SimpleTreeVisitor.java Wed Oct 02 10:59:40 2019 +0200
@@ -264,16 +264,19 @@
}
/**
+ * {@preview Associated with switch expressions, a preview feature of
+ * the Java language.
+ *
+ * This method is associated with <i>switch expressions</i>, a preview
+ * feature of the Java language. Preview features
+ * may be removed in a future release, or upgraded to permanent
+ * features of the Java language.}
+ *
* {@inheritDoc} This implementation calls {@code defaultAction}.
*
* @param node {@inheritDoc}
* @param p {@inheritDoc}
* @return the result of {@code defaultAction}
- *
- * @preview
- * This method is modeling switch expressions,
- * which are part of a preview feature and may be removed
- * if the preview feature is removed.
*/
@Override
@jdk.internal.PreviewFeature(feature=jdk.internal.PreviewFeature.Feature.SWITCH_EXPRESSIONS)
--- a/src/jdk.compiler/share/classes/com/sun/source/util/TreeScanner.java Wed Sep 25 21:19:21 2019 +0200
+++ b/src/jdk.compiler/share/classes/com/sun/source/util/TreeScanner.java Wed Oct 02 10:59:40 2019 +0200
@@ -335,16 +335,19 @@
}
/**
+ * {@preview Associated with switch expressions, a preview feature of
+ * the Java language.
+ *
+ * This method is associated with <i>switch expressions</i>, a preview
+ * feature of the Java language. Preview features
+ * may be removed in a future release, or upgraded to permanent
+ * features of the Java language.}
+ *
* {@inheritDoc} This implementation scans the children in left to right order.
*
* @param node {@inheritDoc}
* @param p {@inheritDoc}
* @return the result of scanning
- *
- * @preview
- * This method is modeling switch expressions,
- * which are part of a preview feature and may be removed
- * if the preview feature is removed.
*/
@Override
@jdk.internal.PreviewFeature(feature=jdk.internal.PreviewFeature.Feature.SWITCH_EXPRESSIONS)
@@ -936,16 +939,19 @@
}
/**
+ * {@preview Associated with switch expressions, a preview feature of
+ * the Java language.
+ *
+ * This method is associated with <i>switch expressions</i>, a preview
+ * feature of the Java language. Preview features
+ * may be removed in a future release, or upgraded to permanent
+ * features of the Java language.}
+ *
* {@inheritDoc} This implementation returns {@code null}.
*
* @param node {@inheritDoc}
* @param p {@inheritDoc}
* @return the result of scanning
- *
- * @preview
- * This method is modeling switch expressions,
- * which are part of a preview feature and may be removed
- * if the preview feature is removed.
*/
@Override
@jdk.internal.PreviewFeature(feature=jdk.internal.PreviewFeature.Feature.SWITCH_EXPRESSIONS)