Skip to content

Commit cb5cdd7

Browse files
jonathan-gibbonsjonathan-gibbons
committed
8254721: Improve support for conditionally generated files
Reviewed-by: hannesw
1 parent 0001435 commit cb5cdd7

File tree

25 files changed

+257
-60
lines changed

25 files changed

+257
-60
lines changed

‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ConstantsSummaryWriterImpl.java

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,7 @@ public ConstantsSummaryWriterImpl(HtmlConfiguration configuration) {
8989
constantsTableHeader = new TableHeader(
9090
contents.modifierAndTypeLabel, contents.constantFieldLabel, contents.valueLabel);
9191
this.navBar = new Navigation(null, configuration, PageMode.CONSTANT_VALUES, path);
92+
configuration.conditionalPages.add(HtmlConfiguration.ConditionalPage.CONSTANT_VALUES);
9293
}
9394

9495
@Override

‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/DeprecatedListWriter.java

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -263,32 +263,33 @@ public DeprecatedListWriter(HtmlConfiguration configuration, DocPath filename) {
263263
* @throws DocFileIOException if there is a problem writing the deprecated list
264264
*/
265265
public static void generate(HtmlConfiguration configuration) throws DocFileIOException {
266-
DocPath filename = DocPaths.DEPRECATED_LIST;
267-
DeprecatedListWriter depr = new DeprecatedListWriter(configuration, filename);
268-
depr.generateDeprecatedListFile(
269-
new DeprecatedAPIListBuilder(configuration));
266+
if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.DEPRECATED)) {
267+
DocPath filename = DocPaths.DEPRECATED_LIST;
268+
DeprecatedListWriter depr = new DeprecatedListWriter(configuration, filename);
269+
depr.generateDeprecatedListFile(configuration.deprecatedAPIListBuilder);
270+
}
270271
}
271272

272273
/**
273274
* Generate the deprecated API list.
274275
*
275-
* @param deprapi list of deprecated API built already.
276+
* @param deprAPI list of deprecated API built already.
276277
* @throws DocFileIOException if there is a problem writing the deprecated list
277278
*/
278-
protected void generateDeprecatedListFile(DeprecatedAPIListBuilder deprapi)
279+
protected void generateDeprecatedListFile(DeprecatedAPIListBuilder deprAPI)
279280
throws DocFileIOException {
280281
HtmlTree body = getHeader();
281-
bodyContents.addMainContent(getContentsList(deprapi));
282+
bodyContents.addMainContent(getContentsList(deprAPI));
282283
String memberTableSummary;
283284
Content content = new ContentBuilder();
284285
for (DeprElementKind kind : DeprElementKind.values()) {
285-
if (deprapi.hasDocumentation(kind)) {
286+
if (deprAPI.hasDocumentation(kind)) {
286287
memberTableSummary = resources.getText("doclet.Member_Table_Summary",
287288
resources.getText(getHeadingKey(kind)),
288289
resources.getText(getSummaryKey(kind)));
289290
TableHeader memberTableHeader = new TableHeader(
290291
contents.getContent(getHeaderKey(kind)), contents.descriptionLabel);
291-
addDeprecatedAPI(deprapi.getSet(kind), getAnchorName(kind),
292+
addDeprecatedAPI(deprAPI.getSet(kind), getAnchorName(kind),
292293
getHeadingKey(kind), memberTableSummary, memberTableHeader, content);
293294
}
294295
}
@@ -302,7 +303,7 @@ protected void generateDeprecatedListFile(DeprecatedAPIListBuilder deprapi)
302303
body.add(bodyContents);
303304
printHtmlDocument(null, description, body);
304305

305-
if (!deprapi.isEmpty() && configuration.mainIndex != null) {
306+
if (!deprAPI.isEmpty() && configuration.mainIndex != null) {
306307
configuration.mainIndex.add(IndexItem.of(IndexItem.Category.TAGS,
307308
resources.getText("doclet.Deprecated_API"), path));
308309
}

‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HelpWriter.java

Lines changed: 39 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -235,7 +235,7 @@ protected void addHelpFileContents(Content contentTree) {
235235
}
236236

237237
// Deprecated
238-
if (!(options.noDeprecatedList() || options.noDeprecated())) {
238+
if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.DEPRECATED)) {
239239
section = newHelpSection(contents.deprecatedAPI);
240240
Content deprBody = getContent("doclet.help.deprecated.body",
241241
links.createLink(DocPaths.DEPRECATED_LIST, resources.getText("doclet.Deprecated_API")));
@@ -255,34 +255,49 @@ protected void addHelpFileContents(Content contentTree) {
255255
}
256256

257257
// Serialized Form
258-
section = newHelpSection(contents.serializedForm)
259-
.add(HtmlTree.P(getContent("doclet.help.serial_form.body")));
260-
contentTree.add(section);
258+
if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.SERIALIZED_FORM)) {
259+
section = newHelpSection(contents.serializedForm)
260+
.add(HtmlTree.P(getContent("doclet.help.serial_form.body")));
261+
contentTree.add(section);
262+
}
261263

262264
// Constant Field Values
263-
section = newHelpSection(contents.constantsSummaryTitle);
264-
Content constantsBody = getContent("doclet.help.constants.body",
265-
links.createLink(DocPaths.CONSTANT_VALUES, resources.getText("doclet.Constants_Summary")));
266-
section.add(HtmlTree.P(constantsBody));
267-
contentTree.add(section);
265+
if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.CONSTANT_VALUES)) {
266+
section = newHelpSection(contents.constantsSummaryTitle);
267+
Content constantsBody = getContent("doclet.help.constants.body",
268+
links.createLink(DocPaths.CONSTANT_VALUES, resources.getText("doclet.Constants_Summary")));
269+
section.add(HtmlTree.P(constantsBody));
270+
contentTree.add(section);
271+
}
272+
273+
// System Properties
274+
if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.SYSTEM_PROPERTIES)) {
275+
section = newHelpSection(contents.systemPropertiesLabel);
276+
Content sysPropsBody = getContent("doclet.help.systemProperties.body",
277+
links.createLink(DocPaths.SYSTEM_PROPERTIES, resources.getText("doclet.systemProperties")));
278+
section.add(HtmlTree.P(sysPropsBody));
279+
contentTree.add(section);
280+
}
268281

269282
// Search
270-
section = newHelpSection(getContent("doclet.help.search.head"));
271-
Content searchIntro = HtmlTree.P(getContent("doclet.help.search.intro"));
272-
Content searchExamples = new HtmlTree(TagName.UL).setStyle(HtmlStyle.helpSectionList);
273-
for (String[] example : SEARCH_EXAMPLES) {
274-
searchExamples.add(HtmlTree.LI(
275-
getContent("doclet.help.search.example",
276-
HtmlTree.CODE(new StringContent(example[0])), example[1])));
283+
if (options.createIndex()) {
284+
section = newHelpSection(getContent("doclet.help.search.head"));
285+
Content searchIntro = HtmlTree.P(getContent("doclet.help.search.intro"));
286+
Content searchExamples = new HtmlTree(TagName.UL).setStyle(HtmlStyle.helpSectionList);
287+
for (String[] example : SEARCH_EXAMPLES) {
288+
searchExamples.add(HtmlTree.LI(
289+
getContent("doclet.help.search.example",
290+
HtmlTree.CODE(new StringContent(example[0])), example[1])));
291+
}
292+
Content searchSpecLink = HtmlTree.A(
293+
resources.getText("doclet.help.search.spec.url", configuration.getDocletVersion().feature()),
294+
getContent("doclet.help.search.spec.title"));
295+
Content searchRefer = HtmlTree.P(getContent("doclet.help.search.refer", searchSpecLink));
296+
section.add(searchIntro)
297+
.add(searchExamples)
298+
.add(searchRefer);
299+
contentTree.add(section);
277300
}
278-
Content searchSpecLink = HtmlTree.A(
279-
resources.getText("doclet.help.search.spec.url", configuration.getDocletVersion().feature()),
280-
getContent("doclet.help.search.spec.title"));
281-
Content searchRefer = HtmlTree.P(getContent("doclet.help.search.refer", searchSpecLink));
282-
section.add(searchIntro)
283-
.add(searchExamples)
284-
.add(searchRefer);
285-
contentTree.add(section);
286301

287302
contentTree.add(new HtmlTree(TagName.HR))
288303
.add(HtmlTree.SPAN(HtmlStyle.helpFootnote,

‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlConfiguration.java

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,10 +27,12 @@
2727

2828
import java.util.ArrayList;
2929
import java.util.Date;
30+
import java.util.EnumSet;
3031
import java.util.HashMap;
3132
import java.util.List;
3233
import java.util.Locale;
3334
import java.util.Map;
35+
import java.util.Set;
3436
import java.util.stream.Collectors;
3537
import javax.lang.model.element.Element;
3638
import javax.lang.model.element.PackageElement;
@@ -47,14 +49,15 @@
4749
import jdk.javadoc.doclet.Taglet;
4850
import jdk.javadoc.internal.Versions;
4951
import jdk.javadoc.internal.doclets.toolkit.BaseConfiguration;
52+
import jdk.javadoc.internal.doclets.toolkit.BaseOptions;
5053
import jdk.javadoc.internal.doclets.toolkit.DocletException;
5154
import jdk.javadoc.internal.doclets.toolkit.Messages;
5255
import jdk.javadoc.internal.doclets.toolkit.Resources;
5356
import jdk.javadoc.internal.doclets.toolkit.WriterFactory;
57+
import jdk.javadoc.internal.doclets.toolkit.util.DeprecatedAPIListBuilder;
5458
import jdk.javadoc.internal.doclets.toolkit.util.DocFile;
5559
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
5660
import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
57-
import jdk.javadoc.internal.doclets.toolkit.util.IndexBuilder;
5861

5962
/**
6063
* Configure the output based on the command-line options.
@@ -105,6 +108,16 @@ public class HtmlConfiguration extends BaseConfiguration {
105108
*/
106109
protected HtmlIndexBuilder mainIndex;
107110

111+
/**
112+
* The collection of deprecated items, if any, to be displayed on the deprecated-list page,
113+
* or null if the page should not be generated.
114+
* The page will not be generated if {@link BaseOptions#noDeprecated() no deprecated items}
115+
* are to be included in the documentation,
116+
* or if the page is {@link HtmlOptions#noDeprecatedList() not wanted},
117+
* or if there are no deprecated elements being documented.
118+
*/
119+
protected DeprecatedAPIListBuilder deprecatedAPIListBuilder;
120+
108121
public final Contents contents;
109122

110123
protected final Messages messages;
@@ -115,6 +128,23 @@ public class HtmlConfiguration extends BaseConfiguration {
115128

116129
private final HtmlOptions options;
117130

131+
/**
132+
* Kinds of conditional pages.
133+
*/
134+
// Note: this should (eventually) be merged with Navigation.PageMode,
135+
// which performs a somewhat similar role
136+
public enum ConditionalPage {
137+
CONSTANT_VALUES, DEPRECATED, SERIALIZED_FORM, SYSTEM_PROPERTIES
138+
}
139+
140+
/**
141+
* A set of values indicating which conditional pages should be generated.
142+
* The set is computed lazily, although values must (obviously) be set before
143+
* they are required, such as when deciding whether or not to generate links
144+
* to these files in the navigation par, on each page, the help file, and so on.
145+
*/
146+
public final Set<ConditionalPage> conditionalPages;
147+
118148
/**
119149
* Constructs the full configuration needed by the doclet, including
120150
* the format-specific part, defined in this class, and the format-independent
@@ -162,6 +192,8 @@ public HtmlConfiguration(Doclet doclet, Locale locale, Reporter reporter) {
162192
v = Runtime.version(); // arguably, the only sensible default
163193
}
164194
docletVersion = v;
195+
196+
conditionalPages = EnumSet.noneOf(ConditionalPage.class);
165197
}
166198

167199
private final Runtime.Version docletVersion;

‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@
4040
import jdk.javadoc.internal.doclets.toolkit.builders.AbstractBuilder;
4141
import jdk.javadoc.internal.doclets.toolkit.builders.BuilderFactory;
4242
import jdk.javadoc.internal.doclets.toolkit.util.ClassTree;
43+
import jdk.javadoc.internal.doclets.toolkit.util.DeprecatedAPIListBuilder;
4344
import jdk.javadoc.internal.doclets.toolkit.util.DocFile;
4445
import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
4546
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
@@ -115,6 +116,21 @@ public HtmlConfiguration getConfiguration() {
115116
return configuration;
116117
}
117118

119+
@Override // defined by AbstractDoclet
120+
public void generateClassFiles(DocletEnvironment docEnv, ClassTree classTree) throws DocletException {
121+
122+
if (!(configuration.getOptions().noDeprecated()
123+
|| configuration.getOptions().noDeprecatedList())) {
124+
DeprecatedAPIListBuilder builder = new DeprecatedAPIListBuilder(configuration);
125+
if (!builder.isEmpty()) {
126+
configuration.deprecatedAPIListBuilder = builder;
127+
configuration.conditionalPages.add(HtmlConfiguration.ConditionalPage.DEPRECATED);
128+
}
129+
}
130+
131+
super.generateClassFiles(docEnv, classTree);
132+
}
133+
118134
/**
119135
* Start the generation of files. Call generate methods in the individual
120136
* writers, which will in turn generate the documentation files. Call the
@@ -155,7 +171,7 @@ protected void generateOtherFiles(ClassTree classtree)
155171
TreeWriter.generate(configuration, classtree);
156172
}
157173

158-
if (!(options.noDeprecatedList() || nodeprecated)) {
174+
if (configuration.conditionalPages.contains((HtmlConfiguration.ConditionalPage.DEPRECATED))) {
159175
DeprecatedListWriter.generate(configuration);
160176
}
161177

‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlOptions.java

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -128,8 +128,8 @@ public class HtmlOptions extends BaseOptions {
128128
private String helpFile = "";
129129

130130
/**
131-
* Argument for command-line option {@code -nodeprecated}.
132-
* True if command-line option "-nodeprecated" is used. Default value is
131+
* Argument for command-line option {@code -nodeprecatedlist}.
132+
* True if command-line option "-nodeprecatedlist" is used. Default value is
133133
* false.
134134
*/
135135
private boolean noDeprecatedList = false;

‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Navigation.java

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -308,8 +308,8 @@ private void addMainNavLinks(Content tree) {
308308
addPageLabel(tree, contents.useLabel, options.classUse());
309309
addTreeLink(tree);
310310
if (documentedPage == PageMode.DEPRECATED) {
311-
addActivePageLink(tree, contents.deprecatedLabel, !(options.noDeprecated()
312-
|| options.noDeprecatedList()));
311+
addActivePageLink(tree, contents.deprecatedLabel,
312+
configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.DEPRECATED));
313313
} else {
314314
addDeprecatedLink(tree);
315315
}
@@ -863,7 +863,7 @@ private void addTreeLink(Content tree) {
863863
}
864864

865865
private void addDeprecatedLink(Content tree) {
866-
if (!(options.noDeprecated() || options.noDeprecatedList())) {
866+
if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.DEPRECATED)) {
867867
tree.add(HtmlTree.LI(links.createLink(pathToRoot.resolve(DocPaths.DEPRECATED_LIST),
868868
contents.deprecatedLabel, "", "")));
869869
}

‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SerializedFormWriterImpl.java

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@ public SerializedFormWriterImpl(HtmlConfiguration configuration) {
6464
super(configuration, DocPaths.SERIALIZED_FORM);
6565
visibleClasses = configuration.getIncludedTypeElements();
6666
this.navBar = new Navigation(null, configuration, PageMode.SERIALIZED_FORM, path);
67+
configuration.conditionalPages.add(HtmlConfiguration.ConditionalPage.SERIALIZED_FORM);
6768
}
6869

6970
/**

‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SystemPropertiesWriter.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,6 @@
4141
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
4242
import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
4343
import jdk.javadoc.internal.doclets.toolkit.util.IndexItem;
44-
import jdk.javadoc.internal.doclets.toolkit.util.IndexItem.Category;
4544

4645
import javax.lang.model.element.Element;
4746
import java.nio.file.Path;
@@ -100,6 +99,7 @@ private static void generate(HtmlConfiguration configuration, DocPath fileName)
10099
}
101100
SystemPropertiesWriter systemPropertiesGen = new SystemPropertiesWriter(configuration, fileName);
102101
systemPropertiesGen.buildSystemPropertiesPage();
102+
configuration.conditionalPages.add(HtmlConfiguration.ConditionalPage.SYSTEM_PROPERTIES);
103103
}
104104

105105
/**

‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -205,6 +205,8 @@ doclet.help.serial_form.body=\
205205
description.
206206
doclet.help.constants.body=\
207207
The {0} page lists the static final fields and their values.
208+
doclet.help.systemProperties.body=\
209+
The {0) page lists references to system properties.
208210
doclet.help.footnote=\
209211
This help file applies to API documentation generated by the standard doclet.
210212
doclet.help.enum.intro=\

‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/BuilderFactory.java

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -76,8 +76,7 @@ public BuilderFactory (BaseConfiguration configuration) {
7676
* @return the builder that builds the constant summary.
7777
*/
7878
public AbstractBuilder getConstantsSummaryBuilder() {
79-
return ConstantsSummaryBuilder.getInstance(context,
80-
writerFactory.getConstantsSummaryWriter());
79+
return ConstantsSummaryBuilder.getInstance(context);
8180
}
8281

8382
/**

‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/ConstantsSummaryBuilder.java

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ public class ConstantsSummaryBuilder extends AbstractBuilder {
5858
/**
5959
* The writer used to write the results.
6060
*/
61-
protected final ConstantsSummaryWriter writer;
61+
protected ConstantsSummaryWriter writer;
6262

6363
/**
6464
* The set of TypeElements that have constant fields.
@@ -89,12 +89,9 @@ public class ConstantsSummaryBuilder extends AbstractBuilder {
8989
* Construct a new ConstantsSummaryBuilder.
9090
*
9191
* @param context the build context.
92-
* @param writer the writer for the summary.
9392
*/
94-
private ConstantsSummaryBuilder(Context context,
95-
ConstantsSummaryWriter writer) {
93+
private ConstantsSummaryBuilder(Context context) {
9694
super(context);
97-
this.writer = writer;
9895
this.typeElementsWithConstFields = new HashSet<>();
9996
this.printedPackageHeaders = new TreeSet<>(utils.comparators.makePackageComparator());
10097
}
@@ -103,16 +100,20 @@ private ConstantsSummaryBuilder(Context context,
103100
* Construct a ConstantsSummaryBuilder.
104101
*
105102
* @param context the build context.
106-
* @param writer the writer for the summary.
107103
* @return the new ConstantsSummaryBuilder
108104
*/
109-
public static ConstantsSummaryBuilder getInstance(Context context,
110-
ConstantsSummaryWriter writer) {
111-
return new ConstantsSummaryBuilder(context, writer);
105+
public static ConstantsSummaryBuilder getInstance(Context context) {
106+
return new ConstantsSummaryBuilder(context);
112107
}
113108

114109
@Override
115110
public void build() throws DocletException {
111+
boolean anyConstants = configuration.packages.stream().anyMatch(this::hasConstantField);
112+
if (!anyConstants) {
113+
return;
114+
}
115+
116+
writer = configuration.getWriterFactory().getConstantsSummaryWriter();
116117
if (writer == null) {
117118
//Doclet does not support this output.
118119
return;

‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DeprecatedAPIListBuilder.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,7 @@ public DeprecatedAPIListBuilder(BaseConfiguration configuration) {
8484
}
8585

8686
public boolean isEmpty() {
87-
return deprecatedMap.values().stream().allMatch(Collection::isEmpty);
87+
return deprecatedMap.values().stream().allMatch(Set::isEmpty);
8888
}
8989

9090
/**

‎test/langtools/jdk/javadoc/doclet/WindowTitles/p1/C1.java

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,4 +26,6 @@
2626
import java.io.Serializable;
2727

2828
public class C1 implements Serializable {
29+
@Deprecated
30+
public static final int ZERO = 0;
2931
}

0 commit comments

Comments
 (0)