Skip to content

Commit eb7d972

Browse files
hnshns
committed
8308659: Use CSS scroll-margin instead of flexbox layout in API documentation
Reviewed-by: jjg
1 parent 7028fb9 commit eb7d972

File tree

37 files changed

+221
-186
lines changed

37 files changed

+221
-186
lines changed

Diff for: ‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AnnotationTypeMemberWriter.java

+3-3
Original file line numberDiff line numberDiff line change
@@ -94,9 +94,9 @@ protected void buildAnnotationTypeMember(Content target) {
9494
for (Element member : members) {
9595
currentMember = member;
9696
Content annotationContent = getAnnotationHeaderContent(currentMember);
97-
98-
buildAnnotationTypeMemberChildren(annotationContent);
99-
97+
Content div = HtmlTree.DIV(HtmlStyle.horizontalScroll);
98+
buildAnnotationTypeMemberChildren(div);
99+
annotationContent.add(div);
100100
memberList.add(writer.getMemberListItem(annotationContent));
101101
}
102102
Content annotationDetails = getAnnotationDetails(annotationDetailsHeader, memberList);

Diff for: ‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassWriter.java

+1-1
Original file line numberDiff line numberDiff line change
@@ -158,7 +158,7 @@ protected void buildClassTree(Content classContent) {
158158
* @param target the content to which the documentation will be added
159159
*/
160160
protected void buildClassInfo(Content target) {
161-
Content c = new ContentBuilder();
161+
Content c = HtmlTree.DIV(HtmlStyle.horizontalScroll);
162162
buildParamInfo(c);
163163
buildSuperInterfacesInfo(c);
164164
buildImplementedInterfacesInfo(c);

Diff for: ‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ConstructorWriter.java

+7-7
Original file line numberDiff line numberDiff line change
@@ -106,13 +106,13 @@ protected void buildConstructorDoc(Content target) {
106106
for (Element constructor : constructors) {
107107
currentConstructor = (ExecutableElement)constructor;
108108
Content constructorContent = getConstructorHeaderContent(currentConstructor);
109-
110-
buildSignature(constructorContent);
111-
buildDeprecationInfo(constructorContent);
112-
buildPreviewInfo(constructorContent);
113-
buildConstructorComments(constructorContent);
114-
buildTagInfo(constructorContent);
115-
109+
Content div = HtmlTree.DIV(HtmlStyle.horizontalScroll);
110+
buildSignature(div);
111+
buildDeprecationInfo(div);
112+
buildPreviewInfo(div);
113+
buildConstructorComments(div);
114+
buildTagInfo(div);
115+
constructorContent.add(div);
116116
memberList.add(getMemberListItem(constructorContent));
117117
}
118118
Content constructorDetails = getConstructorDetails(constructorDetailsHeader, memberList);

Diff for: ‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/EnumConstantWriter.java

+7-7
Original file line numberDiff line numberDiff line change
@@ -73,13 +73,13 @@ protected void buildEnumConstant(Content target) {
7373
for (Element enumConstant : enumConstants) {
7474
currentElement = (VariableElement)enumConstant;
7575
Content enumConstantContent = getEnumConstantsHeader(currentElement);
76-
77-
buildSignature(enumConstantContent);
78-
buildDeprecationInfo(enumConstantContent);
79-
buildPreviewInfo(enumConstantContent);
80-
buildEnumConstantComments(enumConstantContent);
81-
buildTagInfo(enumConstantContent);
82-
76+
Content div = HtmlTree.DIV(HtmlStyle.horizontalScroll);
77+
buildSignature(div);
78+
buildDeprecationInfo(div);
79+
buildPreviewInfo(div);
80+
buildEnumConstantComments(div);
81+
buildTagInfo(div);
82+
enumConstantContent.add(div);
8383
memberList.add(getMemberListItem(enumConstantContent));
8484
}
8585
Content enumConstantDetails = getEnumConstantsDetails(

Diff for: ‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/FieldWriter.java

+7-7
Original file line numberDiff line numberDiff line change
@@ -83,13 +83,13 @@ protected void buildFieldDoc(Content target) {
8383
for (Element element : fields) {
8484
currentElement = (VariableElement)element;
8585
Content fieldContent = getFieldHeaderContent(currentElement);
86-
87-
buildSignature(fieldContent);
88-
buildDeprecationInfo(fieldContent);
89-
buildPreviewInfo(fieldContent);
90-
buildFieldComments(fieldContent);
91-
buildTagInfo(fieldContent);
92-
86+
Content div = HtmlTree.DIV(HtmlStyle.horizontalScroll);
87+
buildSignature(div);
88+
buildDeprecationInfo(div);
89+
buildPreviewInfo(div);
90+
buildFieldComments(div);
91+
buildTagInfo(div);
92+
fieldContent.add(div);
9393
memberList.add(getMemberListItem(fieldContent));
9494
}
9595
Content fieldDetails = getFieldDetails(fieldDetailsHeader, memberList);

Diff for: ‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java

+4-4
Original file line numberDiff line numberDiff line change
@@ -504,7 +504,7 @@ public String getWindowTitle(String title) {
504504
*
505505
* @return the {@code <header>} element
506506
*/
507-
protected HtmlTree getHeader(Navigation.PageMode pageMode) {
507+
protected Content getHeader(Navigation.PageMode pageMode) {
508508
return getHeader(pageMode, null);
509509
}
510510

@@ -517,10 +517,10 @@ protected HtmlTree getHeader(Navigation.PageMode pageMode) {
517517
*
518518
* @return the {@code <header>} element
519519
*/
520-
protected HtmlTree getHeader(Navigation.PageMode pageMode, Element element) {
520+
protected Content getHeader(Navigation.PageMode pageMode, Element element) {
521521
return HtmlTree.HEADER()
522-
.add(RawHtml.of(replaceDocRootDir(options.top())))
523-
.add(getNavBar(pageMode, element).getContent());
522+
.add(RawHtml.of(replaceDocRootDir(options.top())))
523+
.add(getNavBar(pageMode, element).getContent());
524524
}
525525

526526
/**

Diff for: ‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/MethodWriter.java

+7-7
Original file line numberDiff line numberDiff line change
@@ -105,13 +105,13 @@ protected void buildMethodDoc(Content detailsList) {
105105
for (Element method : methods) {
106106
currentMethod = (ExecutableElement)method;
107107
Content methodContent = getMethodHeader(currentMethod);
108-
109-
buildSignature(methodContent);
110-
buildDeprecationInfo(methodContent);
111-
buildPreviewInfo(methodContent);
112-
buildMethodComments(methodContent);
113-
buildTagInfo(methodContent);
114-
108+
Content div = HtmlTree.DIV(HtmlStyle.horizontalScroll);
109+
buildSignature(div);
110+
buildDeprecationInfo(div);
111+
buildPreviewInfo(div);
112+
buildMethodComments(div);
113+
buildTagInfo(div);
114+
methodContent.add(div);
115115
memberList.add(writer.getMemberListItem(methodContent));
116116
}
117117
Content methodDetails = getMethodDetails(methodDetailsHeader, memberList);

Diff for: ‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleWriter.java

+5-4
Original file line numberDiff line numberDiff line change
@@ -191,9 +191,11 @@ protected void buildModuleDoc() throws DocletException {
191191
*/
192192
protected void buildContent() {
193193
Content moduleContent = getContentHeader();
194-
195-
addModuleSignature(moduleContent);
196-
buildModuleDescription(moduleContent);
194+
moduleContent.add(new HtmlTree(TagName.HR));
195+
Content div = HtmlTree.DIV(HtmlStyle.horizontalScroll);
196+
addModuleSignature(div);
197+
buildModuleDescription(div);
198+
moduleContent.add(div);
197199
buildSummary(moduleContent);
198200

199201
addModuleContent(moduleContent);
@@ -882,7 +884,6 @@ protected void addModuleDescription(Content moduleContent) {
882884
}
883885

884886
protected void addModuleSignature(Content moduleContent) {
885-
moduleContent.add(new HtmlTree(TagName.HR));
886887
moduleContent.add(Signatures.getModuleSignature(mdle, this));
887888
}
888889

Diff for: ‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageWriter.java

+11-12
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ public class PackageWriter extends HtmlDocletWriter {
7272
/**
7373
* The HTML element for the section tag being written.
7474
*/
75-
private final HtmlTree section = HtmlTree.SECTION(HtmlStyle.packageDescription, new ContentBuilder());
75+
private final HtmlTree section = HtmlTree.SECTION(HtmlStyle.packageDescription);
7676

7777
private final BodyContents bodyContents = new BodyContents();
7878

@@ -128,10 +128,12 @@ protected void buildPackageDoc() throws DocletException {
128128
*/
129129
protected void buildContent() {
130130
Content packageContent = getContentHeader();
131-
132-
addPackageSignature(packageContent);
133-
buildPackageDescription(packageContent);
134-
buildPackageTags(packageContent);
131+
packageContent.add(new HtmlTree(TagName.HR));
132+
Content div = HtmlTree.DIV(HtmlStyle.horizontalScroll);
133+
addPackageSignature(div);
134+
buildPackageDescription(div);
135+
buildPackageTags(div);
136+
packageContent.add(div);
135137
buildSummary(packageContent);
136138

137139
addPackageContent(packageContent);
@@ -177,10 +179,9 @@ protected void buildAllClassesAndInterfacesSummary(Content summariesList) {
177179
* be added
178180
*/
179181
protected void buildPackageDescription(Content packageContent) {
180-
if (options.noComment()) {
181-
return;
182+
if (!options.noComment()) {
183+
addPackageDescription(packageContent);
182184
}
183-
addPackageDescription(packageContent);
184185
}
185186

186187
/**
@@ -189,10 +190,9 @@ protected void buildPackageDescription(Content packageContent) {
189190
* @param packageContent the content to which the package tags will be added
190191
*/
191192
protected void buildPackageTags(Content packageContent) {
192-
if (options.noComment()) {
193-
return;
193+
if (!options.noComment()) {
194+
addPackageTags(packageContent);
194195
}
195-
addPackageTags(packageContent);
196196
}
197197

198198
protected Content getPackageHeader() {
@@ -422,7 +422,6 @@ protected void addPackageTags(Content packageContent) {
422422
}
423423

424424
protected void addPackageSignature(Content packageContent) {
425-
packageContent.add(new HtmlTree(TagName.HR));
426425
packageContent.add(Signatures.getPackageSignature(packageElement, this));
427426
}
428427

Diff for: ‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PropertyWriter.java

+7-7
Original file line numberDiff line numberDiff line change
@@ -78,13 +78,13 @@ protected void buildPropertyDoc(Content detailsList) {
7878
for (Element property : properties) {
7979
currentProperty = (ExecutableElement)property;
8080
Content propertyContent = getPropertyHeaderContent(currentProperty);
81-
82-
buildSignature(propertyContent);
83-
buildDeprecationInfo(propertyContent);
84-
buildPreviewInfo(propertyContent);
85-
buildPropertyComments(propertyContent);
86-
buildTagInfo(propertyContent);
87-
81+
Content div = HtmlTree.DIV(HtmlStyle.horizontalScroll);
82+
buildSignature(div);
83+
buildDeprecationInfo(div);
84+
buildPreviewInfo(div);
85+
buildPropertyComments(div);
86+
buildTagInfo(div);
87+
propertyContent.add(div);
8888
memberList.add(getMemberListItem(propertyContent));
8989
}
9090
Content propertyDetails = getPropertyDetails(propertyDetailsHeader, memberList);

Diff for: ‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/BodyContents.java

+6-11
Original file line numberDiff line numberDiff line change
@@ -43,20 +43,20 @@
4343
public class BodyContents extends Content {
4444

4545
private final List<Content> mainContents = new ArrayList<>();
46-
private HtmlTree header = null;
47-
private HtmlTree footer = null;
46+
private Content header = null;
47+
private Content footer = null;
4848

4949
public BodyContents addMainContent(Content content) {
5050
mainContents.add(content);
5151
return this;
5252
}
5353

54-
public BodyContents setHeader(HtmlTree header) {
54+
public BodyContents setHeader(Content header) {
5555
this.header = Objects.requireNonNull(header);
5656
return this;
5757
}
5858

59-
public BodyContents setFooter(HtmlTree footer) {
59+
public BodyContents setFooter(Content footer) {
6060
this.footer = footer;
6161
return this;
6262
}
@@ -87,14 +87,9 @@ private Content toContent() {
8787
if (header == null)
8888
throw new NullPointerException();
8989

90-
HtmlTree flexHeader = header.addStyle(HtmlStyle.flexHeader);
91-
92-
var flexContent = HtmlTree.DIV(HtmlStyle.flexContent)
90+
return new ContentBuilder()
91+
.add(header)
9392
.add(HtmlTree.MAIN().add(mainContents))
9493
.add(footer == null ? Text.EMPTY : footer);
95-
96-
return HtmlTree.DIV(HtmlStyle.flexBox)
97-
.add(flexHeader)
98-
.add(flexContent);
9994
}
10095
}

Diff for: ‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlStyle.java

+6-24
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright (c) 2010, 2022, Oracle and/or its affiliates. All rights reserved.
2+
* Copyright (c) 2010, 2023, Oracle and/or its affiliates. All rights reserved.
33
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
44
*
55
* This code is free software; you can redistribute it and/or modify it
@@ -563,29 +563,6 @@ public enum HtmlStyle {
563563
notes,
564564
//</editor-fold>
565565

566-
//<editor-fold desc="flex layout">
567-
//
568-
// The following constants are used for the components of the top-level structures for "flex" layout.
569-
570-
/**
571-
* The class of the top-level {@code div} element used to arrange for "flex" layout in
572-
* a browser window. The element should contain two child elements: one with class
573-
* {@link #flexHeader flex-header} and one with class {@link #flexContent flex-content}.
574-
*/
575-
flexBox,
576-
577-
/**
578-
* The class of the {@code header} element within a {@link #flexBox flex-box} container.
579-
* The element is always displayed at the top of the viewport.
580-
*/
581-
flexHeader,
582-
583-
/**
584-
* The class of the {@code div} element within a {@link #flexBox flex-box} container
585-
* This element appears below the header and can be scrolled if too big for the available height.
586-
*/
587-
flexContent,
588-
//</editor-fold>
589566

590567
//<editor-fold desc="signatures">
591568
//
@@ -964,6 +941,11 @@ public enum HtmlStyle {
964941
*/
965942
horizontal,
966943

944+
/**
945+
* The class of a {@code div} element that allows its horizontal overflow to be scrolled.
946+
*/
947+
horizontalScroll,
948+
967949
/**
968950
* The class of a {@code span} element containing implementation details of
969951
* a "provides" entry in a module page.

Diff for: ‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/script.js

+5-22
Original file line numberDiff line numberDiff line change
@@ -227,27 +227,10 @@ function switchCopyLabel(button, span) {
227227
}, 100);
228228
}, 1900);
229229
}
230-
// Workaround for scroll position not being included in browser history (8249133)
230+
// Dynamically set scroll margin to accomodate for draft header
231231
document.addEventListener("DOMContentLoaded", function(e) {
232-
var contentDiv = document.querySelector("div.flex-content");
233-
window.addEventListener("popstate", function(e) {
234-
if (e.state !== null) {
235-
contentDiv.scrollTop = e.state;
236-
}
237-
});
238-
window.addEventListener("hashchange", function(e) {
239-
history.replaceState(contentDiv.scrollTop, document.title);
240-
});
241-
var timeoutId;
242-
contentDiv.addEventListener("scroll", function(e) {
243-
if (timeoutId) {
244-
clearTimeout(timeoutId);
245-
}
246-
timeoutId = setTimeout(function() {
247-
history.replaceState(contentDiv.scrollTop, document.title);
248-
}, 100);
249-
});
250-
if (!location.hash) {
251-
history.replaceState(contentDiv.scrollTop, document.title);
252-
}
232+
document.querySelectorAll(':not(input)[id]').forEach(
233+
function(c) {
234+
c.style["scroll-margin-top"] = Math.ceil(document.querySelector("header").offsetHeight) + "px"
235+
});
253236
});

0 commit comments

Comments
 (0)