# HG changeset patch # User jlahoda # Date 1570006780 -7200 # Node ID 4c8a6d1d066c6cd3e21ec85a07d6695060c30927 # Parent ebb1ff3d6707d762b56b67e8238f736bcd0b1058 Improving appearance of javadoc of the APIs associated with preview features. diff -r ebb1ff3d6707 -r 4c8a6d1d066c make/jdk/src/classes/build/tools/taglet/Preview.java --- 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 tags, Element elem) { - StringBuilder sb = new StringBuilder(); - sb.append("
Preview Feature:\n"); - for (DocTree tag : tags) { - UnknownBlockTagTree ubt = (UnknownBlockTagTree) tag; - sb.append("
Preview: ") - .append(ubt.getContent()); + UnknownInlineTagTree previewTag = (UnknownInlineTagTree) tags.get(0); + List 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 "
" + summary + "

"; } - return sb.toString(); + return "
" + details + "

"; } } diff -r ebb1ff3d6707 -r 4c8a6d1d066c src/java.base/share/classes/java/lang/String.java --- 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 text blocks, 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 text blocks, 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. *

@@ -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 text blocks, 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) diff -r ebb1ff3d6707 -r 4c8a6d1d066c src/jdk.compiler/share/classes/com/sun/source/tree/CaseTree.java --- 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 switch expressions, 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 getStatements(); /** + * {@preview Associated with switch expressions, a preview feature of + * the Java language. + * + * This method is associated with switch expressions, 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 switch expressions, 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 switch expressions, 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: *

* * @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") diff -r ebb1ff3d6707 -r 4c8a6d1d066c src/jdk.compiler/share/classes/com/sun/source/tree/SwitchExpressionTree.java --- 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 switch expressions, 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 { diff -r ebb1ff3d6707 -r 4c8a6d1d066c src/jdk.compiler/share/classes/com/sun/source/tree/Tree.java --- 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 switch expressions, 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 switch expressions, 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") diff -r ebb1ff3d6707 -r 4c8a6d1d066c src/jdk.compiler/share/classes/com/sun/source/tree/TreeVisitor.java --- 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 switch expressions, 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 switch expressions, 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") diff -r ebb1ff3d6707 -r 4c8a6d1d066c src/jdk.compiler/share/classes/com/sun/source/tree/YieldTree.java --- 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 switch expressions, 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 { diff -r ebb1ff3d6707 -r 4c8a6d1d066c src/jdk.compiler/share/classes/com/sun/source/util/SimpleTreeVisitor.java --- 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 switch expressions, 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) diff -r ebb1ff3d6707 -r 4c8a6d1d066c src/jdk.compiler/share/classes/com/sun/source/util/TreeScanner.java --- 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 switch expressions, 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 switch expressions, 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)