8318416: Superscript marks should use consistent font style

Reviewed-by: liach
This commit is contained in:
Hannes Wallnöfer 2024-11-26 18:50:50 +00:00
parent c5de307284
commit 9458a4355f
10 changed files with 104 additions and 110 deletions

View File

@ -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;
}

View File

@ -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)));
}
}

View File

@ -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));

View File

@ -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 = " ";
}

View File

@ -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.
*/

View File

@ -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;
}

View File

@ -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.
*

View File

@ -364,23 +364,23 @@ public class TestErasure extends JavadocTester {
checkExit(Exit.OK);
checkOutput("preview-list.html", true, """
<div class="col-summary-item-name even-row-color method method-tab1">\
<a href="java.base/p/Foo.html#m(T)">p.Foo.m<wbr>(T)</a><sup>\
<a href="java.base/p/Foo.html#m(T)">p.Foo.m<wbr>(T)</a><sup class="preview-mark">\
<a href="java.base/p/Foo.html#preview-m(T)">PREVIEW</a></sup></div>
<div class="col-second even-row-color method method-tab1">Test Feature</div>
<div class="col-last even-row-color method method-tab1"></div>
<div class="col-summary-item-name odd-row-color method method-tab1">\
<a href="java.base/p/Foo.html#m(p.Y)">p.Foo.m<wbr>(T)</a><sup>\
<a href="java.base/p/Foo.html#m(p.Y)">p.Foo.m<wbr>(T)</a><sup class="preview-mark">\
<a href="java.base/p/Foo.html#preview-m(p.Y)">PREVIEW</a></sup></div>
<div class="col-second odd-row-color method method-tab1">Test Feature</div>
<div class="col-last odd-row-color method method-tab1"></div>""");
checkOutput("preview-list.html", true, """
<div class="col-summary-item-name even-row-color constructor constructor-tab1">\
<a href="java.base/p/Foo.html#%3Cinit%3E(T)">p.Foo<wbr>(T)</a><sup>\
<a href="java.base/p/Foo.html#%3Cinit%3E(T)">p.Foo<wbr>(T)</a><sup class="preview-mark">\
<a href="java.base/p/Foo.html#preview-%3Cinit%3E(T)">PREVIEW</a></sup></div>
<div class="col-second even-row-color constructor constructor-tab1">Test Feature</div>
<div class="col-last even-row-color constructor constructor-tab1"></div>
<div class="col-summary-item-name odd-row-color constructor constructor-tab1">\
<a href="java.base/p/Foo.html#%3Cinit%3E(p.Y)">p.Foo<wbr>(T)</a><sup>\
<a href="java.base/p/Foo.html#%3Cinit%3E(p.Y)">p.Foo<wbr>(T)</a><sup class="preview-mark">\
<a href="java.base/p/Foo.html#preview-%3Cinit%3E(p.Y)">PREVIEW</a></sup></div>
<div class="col-second odd-row-color constructor constructor-tab1">Test Feature</div>
<div class="col-last odd-row-color constructor constructor-tab1"></div>""");

View File

@ -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,
"<code><a href=\"TestPreviewDeclaration.html\" title=\"interface in pkg\">TestPreviewDeclaration</a></code>");
checkOutput("m/pkg/TestPreviewAPIUse.html", true,
"<a href=\"" + doc + "java.base/preview/Core.html\" title=\"class or interface in preview\" class=\"external-link\">Core</a><sup><a href=\"" + doc + "java.base/preview/Core.html#preview-preview.Core\" title=\"class or interface in preview\" class=\"external-link\">PREVIEW</a>");
"<a href=\"" + doc + "java.base/preview/Core.html\" title=\"class or interface in preview\" class="
+ "\"external-link\">Core</a><sup class=\"preview-mark\"><a href=\"" + doc + "java.base/pr"
+ "eview/Core.html#preview-preview.Core\" title=\"class or interface in preview\" class=\""
+ "external-link\">PREVIEW</a>");
checkOutput("m/pkg/DocAnnotation.html", true,
"<span class=\"modifiers\">public @interface </span><span class=\"element-name type-name-label\">DocAnnotation</span>");
checkOutput("m/pkg/DocAnnotationUse1.html", true,
@ -106,7 +109,9 @@ public class TestPreview extends JavadocTester {
<div class="table-header col-first sort-asc" onclick="sortTable(this, 0, 3)">Package</div>
<div class="table-header col-second" onclick="sortTable(this, 1, 3)">Preview Feature</div>
<div class="table-header col-last">Description</div>
<div class="col-summary-item-name even-row-color package package-tab1"><a href="java.base/preview/package-summary.html">preview</a><sup><a href="java.base/preview/package-summary.html#preview-preview">PREVIEW</a></sup></div>
<div class="col-summary-item-name even-row-color package package-tab1"><a href="java.base/prev\
iew/package-summary.html">preview</a><sup class="preview-mark"><a href="java.base/preview/pack\
age-summary.html#preview-preview">PREVIEW</a></sup></div>
<div class="col-second even-row-color package package-tab1">Test Feature</div>
<div class="col-last even-row-color package package-tab1">
<div class="block">Preview package.</div>
@ -122,7 +127,9 @@ public class TestPreview extends JavadocTester {
<div class="table-header col-first sort-asc" onclick="sortTable(this, 0, 3)">Record Class</div>
<div class="table-header col-second" onclick="sortTable(this, 1, 3)">Preview Feature</div>
<div class="table-header col-last">Description</div>
<div class="col-summary-item-name even-row-color record-class record-class-tab1"><a href="java.base/preview/CoreRecord.html" title="class in preview">preview.CoreRecord</a><sup><a href="java.base/preview/CoreRecord.html#preview-preview.CoreRecord">PREVIEW</a></sup></div>
<div class="col-summary-item-name even-row-color record-class record-class-tab1"><a href="java\
.base/preview/CoreRecord.html" title="class in preview">preview.CoreRecord</a><sup class="prev\
iew-mark"><a href="java.base/preview/CoreRecord.html#preview-preview.CoreRecord">PREVIEW</a></sup></div>
<div class="col-second even-row-color record-class record-class-tab1">Test Feature</div>
<div class="col-last even-row-color record-class record-class-tab1"></div>
</div>
@ -137,7 +144,9 @@ public class TestPreview extends JavadocTester {
<div class="table-header col-first sort-asc" onclick="sortTable(this, 0, 3)">Method</div>
<div class="table-header col-second" onclick="sortTable(this, 1, 3)">Preview Feature</div>
<div class="table-header col-last">Description</div>
<div class="col-summary-item-name even-row-color method method-tab1"><a href="java.base/preview/CoreRecordComponent.html#i()">preview.CoreRecordComponent.i()</a><sup><a href="java.base/preview/CoreRecordComponent.html#preview-i()">PREVIEW</a></sup></div>
<div class="col-summary-item-name even-row-color method method-tab1"><a href="java.base/previe\
w/CoreRecordComponent.html#i()">preview.CoreRecordComponent.i()</a><sup class="preview-mark"><\
a href="java.base/preview/CoreRecordComponent.html#preview-i()">PREVIEW</a></sup></div>
<div class="col-second even-row-color method method-tab1">Test Feature</div>
<div class="col-last even-row-color method method-tab1">
<div class="block">Returns the value of the <code>i</code> record component.</div>
@ -160,16 +169,16 @@ public class TestPreview extends JavadocTester {
</ol>""",
"""
<div class="block">Preview feature. Links: <a href="CoreRecord.html" title="cla\
ss in preview"><code>CoreRecord</code></a><sup><a href="CoreRecord.html#preview\
-preview.CoreRecord">PREVIEW</a></sup>, <a href="CoreRecord.html" title="class \
in preview"><code>core record</code></a><sup><a href="CoreRecord.html#preview-p\
review.CoreRecord">PREVIEW</a></sup>,
ss in preview"><code>CoreRecord</code></a><sup class="preview-mark"><a href="Co\
reRecord.html#preview-preview.CoreRecord">PREVIEW</a></sup>, <a href="CoreRecor\
d.html" title="class in preview"><code>core record</code></a><sup class="previe\
w-mark"><a href="CoreRecord.html#preview-preview.CoreRecord">PREVIEW</a></sup>,
<a href="CoreRecord.html" title="class in preview">CoreRecord</a>, <a href="Co\
reRecord.html" title="class in preview">core record</a>.</div>""",
"""
<li><a href="CoreRecord.html" title="class in preview"><code>CoreRecord</code><\
/a><sup><a href="CoreRecord.html#preview-preview.CoreRecord">PREVIEW</a></sup><\
/li>
/a><sup class="preview-mark"><a href="CoreRecord.html#preview-preview.CoreRecor\
d">PREVIEW</a></sup></li>
<li><a href="CoreRecord.html" title="class in preview">core record</a></li>""");
// 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,
"<p><a href=\"#test()\"><code>test()</code></a></p>",
"<p><a href=\"#testNoPreviewInSig()\"><code>testNoPreviewInSig()</code></a></p>",
"title=\"class or interface in java.util\" class=\"external-link\">List</a>&lt;<a href=\"API.html\" title=\"class in api\">API</a><sup><a href=\"#preview-api.API\">PREVIEW</a></sup>&gt;");
"title=\"class or interface in java.util\" class=\"external-link\">List</a>&lt;<a href=\"API.h"
+ "tml\" title=\"class in api\">API</a><sup class=\"preview-mark\"><a href=\"#preview-"
+ "api.API\">PREVIEW</a></sup>&gt;");
checkOutput("api2/api/API2.html", true,
"<a href=\"API.html#test()\"><code>API.test()</code></a><sup><a href=\"API.html#preview-api.API\">PREVIEW</a></sup>",
"<a href=\"API.html#testNoPreviewInSig()\"><code>API.testNoPreviewInSig()</code></a><sup><a href=\"API.html#preview-api.API\">PREVIEW</a></sup>",
"<a href=\"API3.html#test()\"><code>API3.test()</code></a><sup><a href=\"API3.html#preview-test()\">PREVIEW</a></sup>");
"<a href=\"API.html#test()\"><code>API.test()</code></a><sup class=\"preview-mark\"><a href=\""
+ "API.html#preview-api.API\">PREVIEW</a></sup>",
"<a href=\"API.html#testNoPreviewInSig()\"><code>API.testNoPreviewInSig()</code></a><sup class"
+ "=\"preview-mark\"><a href=\"API.html#preview-api.API\">PREVIEW</a></sup>",
"<a href=\"API3.html#test()\"><code>API3.test()</code></a><sup class=\"preview-mark\"><a href="
+ "\"API3.html#preview-test()\">PREVIEW</a></sup>");
checkOutput("api2/api/API3.html", true,
"<div class=\"block\"><a href=\"#test()\"><code>test()</code></a><sup><a href=\"#preview-test()\">PREVIEW</a></sup></div>");
"<div class=\"block\"><a href=\"#test()\"><code>test()</code></a><sup class=\"preview-mark\"><"
+ "a href=\"#preview-test()\">PREVIEW</a></sup></div>");
}
@Test

View File

@ -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,
"""
<ul class="tag-list-long">
<li><a href="#restrictedMethod()"><code>restrictedMethod()</code></a><sup><a href="\
#restricted-restrictedMethod()">RESTRICTED</a></sup></li>
<li><a href="#restrictedMethod()"><code>restrictedMethod()</code></a><sup class="re\
stricted-mark"><a href="#restricted-restrictedMethod()">RESTRICTED</a></sup></li>
<li><a href="#restrictedPreviewMethod()"><code>restrictedPreviewMethod()</code></a>\
<sup><a href="#preview-restrictedPreviewMethod()">PREVIEW</a></sup>&nbsp;<sup><a hr\
ef="#restricted-restrictedPreviewMethod()">RESTRICTED</a></sup></li>""",
<sup class="preview-mark"><a href="#preview-restrictedPreviewMethod()">PREVIEW</a><\
/sup>&nbsp;<sup class="restricted-mark"><a href="#restricted-restrictedPreviewMetho\
d()">RESTRICTED</a></sup></li>""",
"""
<div class="block"><span class="restricted-label">Restricted.</span></div>
<div class="block">Restricted method.</div>""",
@ -157,15 +158,16 @@ public class TestRestricted extends JavadocTester {
<div class="table-header col-first">Method</div>
<div class="table-header col-last">Description</div>
<div class="col-summary-item-name even-row-color"><a href="pkg/I.html#restrictedMet\
hod()">pkg.I.restrictedMethod()</a><sup><a href="pkg/I.html#restricted-restrictedMe\
thod()">RESTRICTED</a></sup></div>
hod()">pkg.I.restrictedMethod()</a><sup class="restricted-mark"><a href="pkg/I.html\
#restricted-restrictedMethod()">RESTRICTED</a></sup></div>
<div class="col-last even-row-color">
<div class="block">Restricted method.</div>
</div>
<div class="col-summary-item-name odd-row-color"><a href="pkg/I.html#restrictedPrev\
iewMethod()">pkg.I.restrictedPreviewMethod()</a><sup><a href="pkg/I.html#preview-re\
strictedPreviewMethod()">PREVIEW</a></sup>&nbsp;<sup><a href="pkg/I.html#restricted\
-restrictedPreviewMethod()">RESTRICTED</a></sup></div>
iewMethod()">pkg.I.restrictedPreviewMethod()</a><sup class="preview-mark"><a href="\
pkg/I.html#preview-restrictedPreviewMethod()">PREVIEW</a></sup>&nbsp;<sup class="re\
stricted-mark"><a href="pkg/I.html#restricted-restrictedPreviewMethod()">RESTRICTED\
</a></sup></div>
<div class="col-last odd-row-color">
<div class="block">Restricted preview method.</div>
</div>""");