From 9458a4355fc0778311c19e67abdbd2c7fadd15e7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hannes=20Walln=C3=B6fer?= Date: Tue, 26 Nov 2024 18:50:50 +0000 Subject: [PATCH] 8318416: Superscript marks should use consistent font style Reviewed-by: liach --- .../formats/html/HtmlDocletWriter.java | 30 +++++------- .../doclets/formats/html/HtmlLinkFactory.java | 16 ++++--- .../doclets/formats/html/ModuleWriter.java | 6 +-- .../doclets/formats/html/Signatures.java | 8 ++-- .../formats/html/markup/HtmlStyles.java | 10 ++++ .../formats/html/resources/stylesheet.css | 22 ++++++--- .../jdk/javadoc/internal/html/HtmlTree.java | 45 ++---------------- .../doclet/testErasure/TestErasure.java | 8 ++-- .../doclet/testPreview/TestPreview.java | 47 ++++++++++++------- .../doclet/testRestricted/TestRestricted.java | 22 +++++---- 10 files changed, 104 insertions(+), 110 deletions(-) diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java index 9bb1ebaaf62..3f20c7dfd76 100644 --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java @@ -791,19 +791,16 @@ public abstract class HtmlDocletWriter { } if (targetLink != null) { if (flags.contains(ElementFlag.PREVIEW)) { - return new ContentBuilder( - links.createLink(targetLink, label), - HtmlTree.SUP(links.createLink(targetLink.withFragment(htmlIds.forPreviewSection(packageElement).name()), - contents.previewMark)) - ); + return new ContentBuilder(links.createLink(targetLink, label), + HtmlTree.SUP(HtmlStyles.previewMark, + links.createLink(targetLink.withFragment(htmlIds.forPreviewSection(packageElement).name()), + contents.previewMark))); } return links.createLink(targetLink, label); } else { if (flags.contains(ElementFlag.PREVIEW)) { - return new ContentBuilder( - label, - HtmlTree.SUP(contents.previewMark) - ); + return new ContentBuilder(label, + HtmlTree.SUP(HtmlStyles.previewMark, contents.previewMark)); } return label; } @@ -835,19 +832,16 @@ public abstract class HtmlDocletWriter { targetLink = new DocLink(pathToRoot.resolve(docPaths.moduleSummary(mdle)), fragment); Content link = links.createLink(targetLink, label, ""); if (flags.contains(ElementFlag.PREVIEW) && label != contents.moduleLabel) { - link = new ContentBuilder( - link, - HtmlTree.SUP(links.createLink(targetLink.withFragment(htmlIds.forPreviewSection(mdle).name()), - contents.previewMark)) - ); + link = new ContentBuilder(link, + HtmlTree.SUP(HtmlStyles.previewMark, + links.createLink(targetLink.withFragment(htmlIds.forPreviewSection(mdle).name()), + contents.previewMark))); } return link; } if (flags.contains(ElementFlag.PREVIEW)) { - return new ContentBuilder( - label, - HtmlTree.SUP(contents.previewMark) - ); + return new ContentBuilder(label, + HtmlTree.SUP(HtmlStyles.previewMark, contents.previewMark)); } return label; } 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 bf210b91ea6..cca5c821c67 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 @@ -43,6 +43,7 @@ import javax.lang.model.type.TypeVariable; import javax.lang.model.type.WildcardType; import javax.lang.model.util.SimpleTypeVisitor14; +import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyles; import jdk.javadoc.internal.doclets.toolkit.BaseConfiguration; import jdk.javadoc.internal.doclets.toolkit.Resources; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; @@ -53,7 +54,6 @@ import jdk.javadoc.internal.html.Content; import jdk.javadoc.internal.html.ContentBuilder; import jdk.javadoc.internal.html.Entity; import jdk.javadoc.internal.html.HtmlId; -import jdk.javadoc.internal.html.HtmlTag; import jdk.javadoc.internal.html.HtmlTree; import jdk.javadoc.internal.html.Text; @@ -337,16 +337,18 @@ public class HtmlLinkFactory { Element previewTarget, ExecutableElement restrictedTarget) { Content spacer = Text.EMPTY; if (flags.contains(ElementFlag.PREVIEW)) { - content.add(HtmlTree.SUP(getSuperscript(fileName, typeElement, - m_writer.htmlIds.forPreviewSection(previewTarget), - m_writer.contents.previewMark))); + content.add(HtmlTree.SUP(HtmlStyles.previewMark, + getSuperscript(fileName, typeElement, + m_writer.htmlIds.forPreviewSection(previewTarget), + m_writer.contents.previewMark))); spacer = Entity.NO_BREAK_SPACE; } if (flags.contains(ElementFlag.RESTRICTED)) { content.add(spacer); - content.add(HtmlTree.SUP(getSuperscript(fileName, typeElement, - m_writer.htmlIds.forRestrictedSection(restrictedTarget), - m_writer.contents.restrictedMark))); + content.add(HtmlTree.SUP(HtmlStyles.restrictedMark, + getSuperscript(fileName, typeElement, + m_writer.htmlIds.forRestrictedSection(restrictedTarget), + m_writer.contents.restrictedMark))); } } diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleWriter.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleWriter.java index 793f619035a..cf4876f7421 100644 --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleWriter.java +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleWriter.java @@ -42,7 +42,6 @@ import javax.lang.model.util.ElementFilter; import com.sun.source.doctree.DeprecatedTree; import com.sun.source.doctree.DocTree; import java.util.function.Predicate; -import java.util.stream.Collectors; import jdk.javadoc.doclet.DocletEnvironment.ModuleMode; import jdk.javadoc.internal.doclets.formats.html.Navigation.PageMode; @@ -614,8 +613,9 @@ public class ModuleWriter extends HtmlDocletWriter { String aepPreviewText = resources.getText("doclet.Indirect_Exports_Summary"); ContentBuilder tableCaption = new ContentBuilder( Text.of(aepPreviewText), - HtmlTree.SUP(links.createLink(previewRequiresTransitiveId, - contents.previewMark))); + HtmlTree.SUP(HtmlStyles.previewMark, + links.createLink(previewRequiresTransitiveId, + contents.previewMark))); var aepPreviewTable = getTable2(tableCaption, indirectPackagesHeader); addIndirectPackages(aepPreviewTable, indirectPackages, m -> m.equals(javaBase)); 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 f1e26879ef4..872fb2dcabe 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 @@ -48,7 +48,6 @@ import jdk.javadoc.internal.doclets.toolkit.util.Utils; import jdk.javadoc.internal.html.Content; import jdk.javadoc.internal.html.ContentBuilder; import jdk.javadoc.internal.html.Entity; -import jdk.javadoc.internal.html.HtmlTag; import jdk.javadoc.internal.html.HtmlTree; import jdk.javadoc.internal.html.Text; @@ -242,9 +241,10 @@ public class Signatures { } content.add(modifier); if (previewModifiers.contains(modifier)) { - content.add(HtmlTree.SUP(writer.links.createLink( - configuration.htmlIds.forPreviewSection(typeElement), - configuration.contents.previewMark))); + content.add(HtmlTree.SUP(HtmlStyles.previewMark, + writer.links.createLink( + configuration.htmlIds.forPreviewSection(typeElement), + configuration.contents.previewMark))); } sep = " "; } 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 e13ed9393a3..6199e6a72a3 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 @@ -687,6 +687,16 @@ public enum HtmlStyles implements HtmlStyle { */ permits, + /** + * The class used for a {@code sup} element marking an element as preview feature. + */ + previewMark, + + /** + * The class used for a {@code sup} element marking a method as restricted. + */ + restrictedMark, + /** * The class of a {@code span} containing the return type in the signature of a method element. */ 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 641a6684444..f8c9b38f122 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 @@ -30,10 +30,11 @@ /* Text colors for body and block elements */ --body-text-color: #282828; --block-text-color: #282828; - /* Background colors for various structural elements */ + /* Background colors for various elements */ --body-background-color: #ffffff; --section-background-color: #f8f8f8; --detail-background-color: #ffffff; + --mark-background-color: #f7f7f7; /* Colors for navigation bar and table captions */ --navbar-background-color: #4D7A97; --navbar-text-color: #ffffff; @@ -141,8 +142,7 @@ ul { code, tt { font-family:var(--code-font-family); } -:not(h1, h2, h3, h4, h5, h6) > code, -:not(h1, h2, h3, h4, h5, h6) > tt { +:not(h1, h2, h3, h4, h5, h6, sup, sub, small, big) > :is(code, tt) { font-size:var(--code-font-size); line-height:1.4em; } @@ -157,9 +157,6 @@ dt code { vertical-align:top; padding-top:4px; } -sup { - font-size:8px; -} button { font-family: var(--body-font-family); font-size: 1em; @@ -823,6 +820,19 @@ div.block { .package-hierarchy-label, .type-name-label, .type-name-link, .search-tag-link, .preview-label, .restricted-label { font-weight:bold; } +sup.preview-mark, +sup.restricted-mark { + font-family: var(--code-font-family); + font-weight: normal; + font-size: 8px; + background-color: var(--mark-background-color); + padding: 1px; + border-radius: 2px; +} +sup.preview-mark > a:link, +sup.restricted-mark > a:link { + font-weight: normal; +} .deprecation-comment, .help-footnote, .preview-comment, .restricted-comment { font-style:italic; } diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/html/HtmlTree.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/html/HtmlTree.java index f1ca45cc040..4c2477babf5 100644 --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/html/HtmlTree.java +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/html/HtmlTree.java @@ -1048,57 +1048,18 @@ public class HtmlTree extends Content { } /** - * Creates an HTML {@code SUP} element with the given content. + * Creates an HTML {@code SUP} element with the given style and content. * + * @param style the style * @param body the content * @return the element */ - public static HtmlTree SUP(Content body) { + public static HtmlTree SUP(HtmlStyle style, Content body) { return new HtmlTree(HtmlTag.SUP) - .add(body); - } - - /** - * Creates an HTML {@code TD} element with the given style and some content. - * - * @param style the style - * @param body the content - * @return the element - */ - public static HtmlTree TD(HtmlStyle style, Content body) { - return new HtmlTree(HtmlTag.TD) .setStyle(style) .add(body); } - /** - * Creates an HTML {@code TH} element with the given style and scope, and some content. - * - * @param style the style - * @param scope the value for the {@code scope} attribute - * @param body the content - * @return the element - */ - public static HtmlTree TH(HtmlStyle style, String scope, Content body) { - return new HtmlTree(HtmlTag.TH) - .setStyle(style) - .put(HtmlAttr.SCOPE, scope) - .add(body); - } - - /** - * Creates an HTML {@code TH} element with the given scope, and some content. - * - * @param scope the value for the {@code scope} attribute - * @param body the content - * @return the element - */ - public static HtmlTree TH(String scope, Content body) { - return new HtmlTree(HtmlTag.TH) - .put(HtmlAttr.SCOPE, scope) - .add(body); - } - /** * Creates an HTML {@code TITLE} element with some content. * diff --git a/test/langtools/jdk/javadoc/doclet/testErasure/TestErasure.java b/test/langtools/jdk/javadoc/doclet/testErasure/TestErasure.java index ee2ec08b884..416d0cd2ec2 100644 --- a/test/langtools/jdk/javadoc/doclet/testErasure/TestErasure.java +++ b/test/langtools/jdk/javadoc/doclet/testErasure/TestErasure.java @@ -364,23 +364,23 @@ public class TestErasure extends JavadocTester { checkExit(Exit.OK); checkOutput("preview-list.html", true, """
\ - p.Foo.m(T)\ + p.Foo.m(T)\ PREVIEW
Test Feature
\ - p.Foo.m(T)\ + p.Foo.m(T)\ PREVIEW
Test Feature
"""); checkOutput("preview-list.html", true, """
\ - p.Foo(T)\ + p.Foo(T)\ PREVIEW
Test Feature
\ - p.Foo(T)\ + p.Foo(T)\ PREVIEW
Test Feature
"""); diff --git a/test/langtools/jdk/javadoc/doclet/testPreview/TestPreview.java b/test/langtools/jdk/javadoc/doclet/testPreview/TestPreview.java index 79658e4c606..7022b02ee88 100644 --- a/test/langtools/jdk/javadoc/doclet/testPreview/TestPreview.java +++ b/test/langtools/jdk/javadoc/doclet/testPreview/TestPreview.java @@ -24,7 +24,7 @@ /* * @test * @bug 8250768 8261976 8277300 8282452 8287597 8325325 8325874 8297879 - * 8331947 8281533 + * 8331947 8281533 8318416 * @summary test generated docs for items declared using preview * @library ../../lib * @modules jdk.javadoc/jdk.javadoc.internal.tool @@ -59,7 +59,10 @@ public class TestPreview extends JavadocTester { checkOutput("m/pkg/TestPreviewDeclarationUse.html", true, "TestPreviewDeclaration"); checkOutput("m/pkg/TestPreviewAPIUse.html", true, - "CorePREVIEW"); + "CorePREVIEW"); checkOutput("m/pkg/DocAnnotation.html", true, "public @interface DocAnnotation"); checkOutput("m/pkg/DocAnnotationUse1.html", true, @@ -106,7 +109,9 @@ public class TestPreview extends JavadocTester {
Package
Preview Feature
Description
-
previewPREVIEW
+
previewPREVIEW
Test Feature
Preview package.
@@ -122,7 +127,9 @@ public class TestPreview extends JavadocTester {
Record Class
Preview Feature
Description
-
preview.CoreRecordPREVIEW
+
preview.CoreRecordPREVIEW
Test Feature
@@ -137,7 +144,9 @@ public class TestPreview extends JavadocTester {
Method
Preview Feature
Description
-
preview.CoreRecordComponent.i()PREVIEW
+
preview.CoreRecordComponent.i()<\ + a href="java.base/preview/CoreRecordComponent.html#preview-i()">PREVIEW
Test Feature
Returns the value of the i record component.
@@ -160,16 +169,16 @@ public class TestPreview extends JavadocTester { """, """
Preview feature. Links: CoreRecordPREVIEW, core recordPREVIEW, + ss in preview">CoreRecordPREVIEW, core recordPREVIEW, CoreRecord, core record.
""", """
  • CoreRecord<\ - /a>PREVIEW<\ - /li> + /a>PREVIEW
  • core record
    • """); // 8331947: Support preview features without JEP should not be included in Preview API page @@ -188,13 +197,19 @@ public class TestPreview extends JavadocTester { checkOutput("api2/api/API.html", true, "

    test()

    ", "

    testNoPreviewInSig()

    ", - "title=\"class or interface in java.util\" class=\"external-link\">List<APIPREVIEW>"); + "title=\"class or interface in java.util\" class=\"external-link\">List<APIPREVIEW>"); checkOutput("api2/api/API2.html", true, - "API.test()PREVIEW", - "API.testNoPreviewInSig()PREVIEW", - "API3.test()PREVIEW"); + "API.test()PREVIEW", + "API.testNoPreviewInSig()PREVIEW", + "API3.test()PREVIEW"); checkOutput("api2/api/API3.html", true, - "
    test()PREVIEW
    "); + "
    test()<" + + "a href=\"#preview-test()\">PREVIEW
    "); } @Test diff --git a/test/langtools/jdk/javadoc/doclet/testRestricted/TestRestricted.java b/test/langtools/jdk/javadoc/doclet/testRestricted/TestRestricted.java index 05b833a55a3..3e9dc7fbf90 100644 --- a/test/langtools/jdk/javadoc/doclet/testRestricted/TestRestricted.java +++ b/test/langtools/jdk/javadoc/doclet/testRestricted/TestRestricted.java @@ -23,7 +23,7 @@ /* * @test - * @bug 8316972 8325217 + * @bug 8316972 8325217 8318416 * @summary Add javadoc support for restricted methods * @library /tools/lib ../../lib * @modules jdk.javadoc/jdk.javadoc.internal.tool @@ -92,11 +92,12 @@ public class TestRestricted extends JavadocTester { checkOutput("pkg/I.html", true, """
    Restricted method.
    pkg.I.restrictedPreviewMethod()PREVIEW RESTRICTED
    + iewMethod()">pkg.I.restrictedPreviewMethod()PREVIEW RESTRICTED\ +
    Restricted preview method.
    """);