From b89cba7517b5b7373988d15f3a22c412455e5cbd Mon Sep 17 00:00:00 2001 From: Nizar Benalla Date: Wed, 27 Nov 2024 15:36:02 +0000 Subject: [PATCH] 8342808: Javadoc should add whitespace between type parameters Reviewed-by: hannesw --- .../doclets/formats/html/ClassWriter.java | 13 +++++++-- .../doclets/formats/html/HtmlLinkFactory.java | 11 +++++--- .../doclets/formats/html/Signatures.java | 11 +------- .../formats/html/markup/HtmlStyles.java | 8 ------ .../formats/html/resources/stylesheet.css | 1 - .../TestGenericTypeLink.java | 23 ++++++++------- .../testInheritance/TestInheritance.java | 4 +-- .../doclet/testInterface/TestInterface.java | 8 +++--- .../TestMethodSignature.java | 28 +++++++++---------- .../TestNewLanguageFeatures.java | 2 +- .../TestTypeAnnotations.java | 26 ++++++++--------- .../testTypeParams/TestTypeParameters.java | 4 +-- 12 files changed, 66 insertions(+), 73 deletions(-) diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassWriter.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassWriter.java index 7b271485f1f..d934a9aab63 100644 --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassWriter.java +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassWriter.java @@ -57,7 +57,6 @@ import jdk.javadoc.internal.doclets.toolkit.util.DocPath; import jdk.javadoc.internal.html.Content; import jdk.javadoc.internal.html.ContentBuilder; import jdk.javadoc.internal.html.HtmlAttr; -import jdk.javadoc.internal.html.HtmlTag; import jdk.javadoc.internal.html.HtmlTree; import jdk.javadoc.internal.html.Text; @@ -78,6 +77,9 @@ public class ClassWriter extends SubWriterHolderWriter { "java.lang.constant.ConstantDesc", "java.io.Serializable"); + /* Length threshold to determine whether to insert whitespace between type parameters */ + protected static final int LONG_TYPE_PARAM = 8; + protected final TypeElement typeElement; protected final ClassTree classTree; @@ -459,9 +461,16 @@ public class ClassWriter extends SubWriterHolderWriter { .linkToSelf(false); // Let's not link to ourselves in the header content.add("<"); var first = true; + boolean longTypeParams = typeParams.stream() + .map(t -> getLink(linkInfo.forType(t.asType()))) + .anyMatch(t -> t.charCount() > ClassWriter.LONG_TYPE_PARAM); for (TypeParameterElement t : typeParams) { if (!first) { - content.add(",").add(HtmlTree.WBR()); + if (longTypeParams) { + content.add(", "); + } else { + content.add(",").add(HtmlTree.WBR()); + } } var typeParamLink = getLink(linkInfo.forType(t.asType())); content.add(needsId diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlLinkFactory.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlLinkFactory.java index cca5c821c67..54da5af14a9 100644 --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlLinkFactory.java +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlLinkFactory.java @@ -401,12 +401,15 @@ public class HtmlLinkFactory { } links.add("<"); boolean many = false; + boolean longTypeParams = vars.stream() + .map(t -> getLink(linkInfo.forType(t))) + .anyMatch(t -> t.charCount() > ClassWriter.LONG_TYPE_PARAM); for (TypeMirror t : vars) { if (many) { - links.add(","); - links.add(HtmlTree.WBR()); - if (linkInfo.addLineBreaksInTypeParameters()) { - links.add(Text.NL); + if (longTypeParams) { + links.add(", "); + } else { + links.add(",").add(HtmlTree.WBR()); } } links.add(getLink(linkInfo.forType(t))); diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Signatures.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Signatures.java index 872fb2dcabe..2a411050000 100644 --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Signatures.java +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Signatures.java @@ -355,9 +355,6 @@ public class Signatures { private Content parameters; private Content exceptions; - // Threshold for length of type parameters before switching from inline to block representation. - private static final int TYPE_PARAMS_MAX_INLINE_LENGTH = 50; - // Threshold for combined length of modifiers, type params and return type before breaking // it up with a line break before the return type. private static final int RETURN_TYPE_MAX_LINE_LENGTH = 50; @@ -532,13 +529,7 @@ public class Signatures { // Apply different wrapping strategies for type parameters // depending on the combined length of type parameters and return type. // Note return type will be null if this is a constructor. - int typeParamLength = typeParameters.charCount(); - - if (typeParamLength >= TYPE_PARAMS_MAX_INLINE_LENGTH) { - target.add(HtmlTree.SPAN(HtmlStyles.typeParametersLong, typeParameters)); - } else { - target.add(HtmlTree.SPAN(HtmlStyles.typeParameters, typeParameters)); - } + target.add(HtmlTree.SPAN(HtmlStyles.typeParameters, typeParameters)); int lineLength = target.charCount() - lastLineSeparator; int newLastLineSeparator = lastLineSeparator; diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlStyles.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlStyles.java index 6199e6a72a3..358f490334b 100644 --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlStyles.java +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlStyles.java @@ -708,14 +708,6 @@ public enum HtmlStyles implements HtmlStyle { */ typeParameters, - /** - * The class of a {@code span} containing type parameters in the signature of an element, - * used when the type parameters are too long to be displayed inline. - * @implNote - * The threshold for choosing between {@code typeParameters} and {@code typeParametersLong} - * is 50 characters. - */ - typeParametersLong, // // diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/stylesheet.css b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/stylesheet.css index f8c9b38f122..bdf84dc0f97 100644 --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/stylesheet.css +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/stylesheet.css @@ -793,7 +793,6 @@ div.block { .type-signature { margin-top: 0; } -.member-signature .type-parameters-long, .member-signature .parameters, .member-signature .exceptions { display: inline-block; diff --git a/test/langtools/jdk/javadoc/doclet/testGenericTypeLink/TestGenericTypeLink.java b/test/langtools/jdk/javadoc/doclet/testGenericTypeLink/TestGenericTypeLink.java index d8bf1fc2bdf..b7f1a95ae1e 100644 --- a/test/langtools/jdk/javadoc/doclet/testGenericTypeLink/TestGenericTypeLink.java +++ b/test/langtools/jdk/javadoc/doclet/testGenericTypeLink/TestGenericTypeLink.java @@ -74,15 +74,15 @@ public class TestGenericTypeLink extends JavadocTester {
  • Map<String,? extends String, ? extends CharSequence>
  • Map<String,? super String, ? super A<String,? \ + ml" title="class or interface in java.lang" class="external-link">String, ? \ extends RuntimeException>>
    • @@ -97,7 +97,7 @@ public class TestGenericTypeLink extends JavadocTester { """
    A<String,String, A.SomeException> link to generic type with label\ @@ -109,7 +109,7 @@ public class TestGenericTypeLink extends JavadocTester {
    Here's a generic link: A<Object,<\ - wbr>Object, \ + RuntimeExcepti\ on>.Inner"""); } @@ -213,4 +213,3 @@ public class TestGenericTypeLink extends JavadocTester { """); } } - diff --git a/test/langtools/jdk/javadoc/doclet/testInheritance/TestInheritance.java b/test/langtools/jdk/javadoc/doclet/testInheritance/TestInheritance.java index fc08c53467c..5ebb5157ecb 100644 --- a/test/langtools/jdk/javadoc/doclet/testInheritance/TestInheritance.java +++ b/test/langtools/jdk/javadoc/doclet/testInheritance/TestInheritance.java @@ -95,8 +95,8 @@ public class TestInheritance extends JavadocTester {
    pkg.B<O,P>
    """); checkOrder("pkg/C.html", """
    java.lang.Object -
    pkg.A<java.lang.String,Q> -
    pkg.B<java.lang.String,Q> +
    pkg.A<java.lang.String, Q> +
    pkg.B<java.lang.String, Q>
    pkg.C<Q>
    """); checkOrder("pkg/D.html", """
    java.lang.Object diff --git a/test/langtools/jdk/javadoc/doclet/testInterface/TestInterface.java b/test/langtools/jdk/javadoc/doclet/testInterface/TestInterface.java index f213d393fdf..214f134f3ad 100644 --- a/test/langtools/jdk/javadoc/doclet/testInterface/TestInterface.java +++ b/test/langtools/jdk/javadoc/doclet/testInterface/TestInterface.java @@ -212,9 +212,9 @@ public class TestInterface extends JavadocTester { ator.OfInt<Integer>, Spliterator.OfPrimitive<T,T, T_C\ - ONS,T_SPLITR extends Spliterator.OfPrimitive<T,<\ @@ -243,8 +243,8 @@ public class TestInterface extends JavadocTester {
    Spliterator.OfPrimitive\ <T,T_CONS,T, T_CONS, T_SPLITR extends <\ a href="Spliterator.OfPrimitive.html" title="interface in pkg2">Spliterator.OfPr\ imitive<public static \ - <T1 extends java.lang.AutoCloseable, - T2 extends java.lang.AutoCloseable, - T3 extends java.lang.AutoCloseable, - T4 extends java.lang.AutoCloseable, - T5 extends java.lang.AutoCloseable, - T6 extends java.lang.AutoCloseable, - T7 extends java.lang.AutoCloseable, + <T1 extends java.lang.AutoCloseable, \ + T2 extends java.lang.AutoCloseable, \ + T3 extends java.lang.AutoCloseable, \ + T4 extends java.lang.AutoCloseable, \ + T5 extends java.lang.AutoCloseable, \ + T6 extends java.lang.AutoCloseable, \ + T7 extends java.lang.AutoCloseable, \ T8 extends java.lang.AutoCloseable> C.Wit\ h8Types<T1,T2,T3,T4,T5,T6,T7,T8>public static <T1 extends java.lang.AutoCloseable, - T2 extends java.lang.AutoCloseable, - T3 extends java.lang.AutoCloseable, - T4 extends java.lang.AutoCloseable, - T5 extends java.lang.AutoCloseable, - T6 extends java.lang.AutoCloseable, - T7 extends java.lang.AutoCloseable, + eters"><T1 extends java.lang.AutoCloseable, \ + T2 extends java.lang.AutoCloseable, \ + T3 extends java.lang.AutoCloseable, \ + T4 extends java.lang.AutoCloseable, \ + T5 extends java.lang.AutoCloseable, \ + T6 extends java.lang.AutoCloseable, \ + T7 extends java.lang.AutoCloseable, \ T8 extends java.lang.AutoCloseable> C.Wit\ h8Types<T1,T2,T3,T4,T5,T6,T7,T8>public <T extends java.util.List, + lass="type-parameters"><T extends java.util.List, \ V> java.lang.String[] meth\ odThatHasTypeParameters(T param1, diff --git a/test/langtools/jdk/javadoc/doclet/testTypeAnnotations/TestTypeAnnotations.java b/test/langtools/jdk/javadoc/doclet/testTypeAnnotations/TestTypeAnnotations.java index 948ed22c418..81c0b4a0b09 100644 --- a/test/langtools/jdk/javadoc/doclet/testTypeAnnotations/TestTypeAnnotations.java +++ b/test/langtools/jdk/javadoc/doclet/testTypeAnnotations/TestTypeAnnotations.java @@ -94,7 +94,7 @@ public class TestTypeAnnotations extends JavadocTester { """
    class TwoBounds<K extends @ClassParamA java.lang.String,V\ + tle="annotation interface in typeannos">@ClassParamA java.lang.String, V\ extends @C\ lassParamB java.lang.String>"""); @@ -122,7 +122,7 @@ public class TestTypeAnnotations extends JavadocTester { """
    Parameterized<@FldA java.lang.String,@FldA java.lang.String, @FldB java.lang.String><\ /span> bothTypeArgs
    """, @@ -163,8 +163,8 @@ public class TestTypeAnnotations extends JavadocTester { >Parameterized<@FldA Parameteri\ zed<@FldA java.lang.String,@FldB java.lang.String>,@FldB java.lang.String>, @FldB java.lang.String> nestedParameterized
    """, @@ -212,8 +212,8 @@ public class TestTypeAnnotations extends JavadocTester { os">MtdParameterized<@MRtnA MtdParameterized<@MRtnA java.lang.String,@MRtnB java.lang.String>,@MRtnA java.lang.String, @MRtnB java.lang.String>, @MRtnB java.lang.String> nestedMtdParameterized()
    """); @@ -226,7 +226,7 @@ public class TestTypeAnnotations extends JavadocTester { ass="element-name">methodExtends()
    """, """ -
    <K extends <\ +
    <K extends <\ a href="MTyParamA.html" title="annotation interface in typeannos">@MTyParamA\ MtdTyParameterized\ <@MTyP\ @@ -242,8 +242,8 @@ public class TestTypeAnnotations extends JavadocTester { """
    public final <\ - span class="type-parameters-long"><K extends @MTyParamA java.lang.String, + span class="type-parameters"><K extends @MTyParamA java.lang.String, \ V extends @MT\ yParamA MtdTyPa\ rameterized<void unannotated(ParaParameterized<java.l\ - ang.String,java.lang.String> a)
    """, + ang.String, java.lang.String> a)
    """, """
    void <@ParamA ParaParameterized<\ /a><@ParamA java.lang.String,@ParamB java.lang.String>,@ParamB java.lang.String>, @ParamB java.lang.String> a)""", @@ -339,7 +339,7 @@ public class TestTypeAnnotations extends JavadocTester { // Test for type annotations on type parameters (TypeParameters.java). checkOutput("typeannos/TestMethods.html", true, """ -
    <K, +
    <K, \ @TyParaA V \ extends @TyPara\ A java.lang.String> diff --git a/test/langtools/jdk/javadoc/doclet/testTypeParams/TestTypeParameters.java b/test/langtools/jdk/javadoc/doclet/testTypeParams/TestTypeParameters.java index dad610acb30..1cf2f054775 100644 --- a/test/langtools/jdk/javadoc/doclet/testTypeParams/TestTypeParameters.java +++ b/test/langtools/jdk/javadoc/doclet/testTypeParams/TestTypeParameters.java @@ -56,8 +56,8 @@ public class TestTypeParameters extends JavadocTester { checkOutput("pkg/C.html", true, """ -
    <W extends java.lang.String, +
    <W extends java.lang.String, \ V extends java.util.List>
    java.lang.Object
    """, "<T> java.lang.Object");