Skip to content

Commit 1e8e543

Browse files
hnslahodaj
hns
and
lahodaj
committed
8216497: javadoc should auto-link to platform classes
Co-authored-by: Jan Lahoda <jlahoda@openjdk.org> Reviewed-by: erikj, jjg
1 parent 04ca660 commit 1e8e543

File tree

51 files changed

+1840
-13
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

51 files changed

+1840
-13
lines changed

‎make/CompileInterimLangtools.gmk‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,7 @@ define SetupInterimModule
7474
EXCLUDE_FILES := $(TOPDIR)/src/$1/share/classes/module-info.java \
7575
Standard.java, \
7676
EXTRA_FILES := $(BUILDTOOLS_OUTPUTDIR)/gensrc/$1.interim/module-info.java, \
77-
COPY := .gif .png .xml .css .js javax.tools.JavaCompilerTool, \
77+
COPY := .gif .png .xml .css .js .txt javax.tools.JavaCompilerTool, \
7878
BIN := $(BUILDTOOLS_OUTPUTDIR)/interim_langtools_modules/$1.interim, \
7979
DISABLED_WARNINGS := module options, \
8080
JAVAC_FLAGS := \

‎make/CompileJavaModules.gmk‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -348,7 +348,7 @@ jdk.dynalink_CLEAN += .properties
348348

349349
################################################################################
350350

351-
jdk.javadoc_COPY += .xml .css .js .png
351+
jdk.javadoc_COPY += .xml .css .js .png .txt
352352

353353
################################################################################
354354

‎make/langtools/src/classes/build/tools/symbolgenerator/CreateSymbols.java‎

Lines changed: 76 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,7 @@
143143
import com.sun.tools.javac.util.Assert;
144144
import com.sun.tools.javac.util.Context;
145145
import com.sun.tools.javac.util.Pair;
146+
import java.util.Optional;
146147

147148
/**
148149
* A tool for processing the .sym.txt files.
@@ -3820,6 +3821,47 @@ private static AnnotationDescription parseAnnotation(String value, int[] valuePo
38203821
}
38213822
//</editor-fold>
38223823

3824+
/**Create sig files for ct.sym reading the classes description from the directory that contains
3825+
* {@code ctDescriptionFile}, using the file as a recipe to create the sigfiles.
3826+
*/
3827+
@SuppressWarnings("unchecked")
3828+
public void createJavadocData(String ctDescriptionFileExtra, String ctDescriptionFile,
3829+
String targetDir, int startVersion) throws IOException {
3830+
LoadDescriptions data = load(ctDescriptionFileExtra != null ? Paths.get(ctDescriptionFileExtra)
3831+
: null,
3832+
Paths.get(ctDescriptionFile));
3833+
3834+
Path target = Paths.get(targetDir);
3835+
3836+
for (PlatformInput version : data.versions) {
3837+
int versionNumber = Integer.parseInt(version.version, Character.MAX_RADIX);
3838+
if (versionNumber < startVersion) {
3839+
continue;
3840+
}
3841+
Path outputFile = target.resolve("element-list-" + versionNumber + ".txt");
3842+
Files.createDirectories(outputFile.getParent());
3843+
try (Writer w = Files.newBufferedWriter(outputFile, StandardCharsets.UTF_8)) {
3844+
Set<ModuleDescription> modules = new TreeSet<>((m1, m2) -> m1.name.compareTo(m2.name));
3845+
modules.addAll(data.modules.values());
3846+
for (ModuleDescription module : modules) {
3847+
if ("jdk.unsupported".equals(module.name)) {
3848+
continue;
3849+
}
3850+
Optional<ModuleHeaderDescription> header = module.header.stream().filter(h -> h.versions.contains(version.version)).findAny();
3851+
if (header.isEmpty()) {
3852+
continue;
3853+
}
3854+
w.write("module:" + module.name);
3855+
w.write("\n");
3856+
for (String pack : header.get().exports) {
3857+
w.write(pack.replace('/', '.'));
3858+
w.write("\n");
3859+
}
3860+
}
3861+
}
3862+
}
3863+
}
3864+
38233865
private static void help() {
38243866
System.err.println("Help...");
38253867
}
@@ -3900,7 +3942,7 @@ public FileVisitResult visitFileFailed(Path file, IOException exc) throws IOExce
39003942
new CreateSymbols().createIncrementalBaseLine(args[1], args[2], args);
39013943
break;
39023944
}
3903-
case "build-ctsym":
3945+
case "build-ctsym": {
39043946
String ctDescriptionFileExtra;
39053947
String ctDescriptionFile;
39063948
String ctSymLocation;
@@ -3939,6 +3981,39 @@ public FileVisitResult visitFileFailed(Path file, IOException exc) throws IOExce
39393981
currentVersion,
39403982
systemModules);
39413983
break;
3984+
}
3985+
case "build-javadoc-data": {
3986+
String ctDescriptionFileExtra;
3987+
String ctDescriptionFile;
3988+
String targetDir;
3989+
int startVersion;
3990+
3991+
if (args.length == 4) {
3992+
ctDescriptionFileExtra = null;
3993+
ctDescriptionFile = args[1];
3994+
targetDir = args[2];
3995+
startVersion = Integer.parseInt(args[3]);
3996+
} else if (args.length == 5) {
3997+
ctDescriptionFileExtra = args[1];
3998+
ctDescriptionFile = args[2];
3999+
targetDir = args[3];
4000+
startVersion = Integer.parseInt(args[4]);
4001+
} else {
4002+
help();
4003+
return ;
4004+
}
4005+
4006+
if (startVersion < 9) {
4007+
System.err.println("The start version must be at least 9!");
4008+
return ;
4009+
}
4010+
4011+
new CreateSymbols().createJavadocData(ctDescriptionFileExtra,
4012+
ctDescriptionFile,
4013+
targetDir,
4014+
startVersion);
4015+
break;
4016+
}
39424017
}
39434018
}
39444019

‎make/langtools/src/classes/build/tools/symbolgenerator/JavadocElementList.java‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
/*
2+
* Copyright (c) 2017, 2018, Oracle and/or its affiliates. All rights reserved.
3+
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+
*
5+
* This code is free software; you can redistribute it and/or modify it
6+
* under the terms of the GNU General Public License version 2 only, as
7+
* published by the Free Software Foundation. Oracle designates this
8+
* particular file as subject to the "Classpath" exception as provided
9+
* by Oracle in the LICENSE file that accompanied this code.
10+
*
11+
* This code is distributed in the hope that it will be useful, but WITHOUT
12+
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+
* version 2 for more details (a copy is included in the LICENSE file that
15+
* accompanied this code).
16+
*
17+
* You should have received a copy of the GNU General Public License version
18+
* 2 along with this work; if not, write to the Free Software Foundation,
19+
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+
*
21+
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+
* or visit www.oracle.com if you need additional information or have any
23+
* questions.
24+
*/
25+
26+
package build.tools.symbolgenerator;
27+
28+
import java.io.IOException;
29+
import java.io.PrintWriter;
30+
import java.io.Writer;
31+
import java.nio.file.Files;
32+
import java.nio.file.Path;
33+
import java.nio.file.Paths;
34+
import java.util.ArrayDeque;
35+
import java.util.Arrays;
36+
import java.util.Deque;
37+
import java.util.List;
38+
import java.util.Set;
39+
import java.util.stream.Collectors;
40+
41+
import javax.lang.model.element.ModuleElement.ExportsDirective;
42+
import javax.lang.model.util.Elements;
43+
import javax.tools.JavaCompiler;
44+
45+
import com.sun.tools.javac.api.JavacTaskImpl;
46+
import com.sun.tools.javac.api.JavacTool;
47+
import com.sun.tools.javac.code.Source;
48+
import com.sun.tools.javac.code.Symbol.ModuleSymbol;
49+
import com.sun.tools.javac.jvm.Target;
50+
import java.util.Map;
51+
import java.util.Map.Entry;
52+
import java.util.TreeMap;
53+
import java.util.TreeSet;
54+
import javax.lang.model.element.ModuleElement;
55+
56+
/**
57+
* Generate list of modules and packages in the current release.
58+
* Used by the javadoc tool.
59+
*/
60+
public class JavadocElementList {
61+
62+
private static void help() {
63+
System.err.println("java JavadocElementList <target-file> <module-source-path> <root-modules>");
64+
}
65+
66+
public static void main(String... args) throws IOException {
67+
if (args.length < 2) {
68+
help();
69+
return ;
70+
}
71+
72+
JavaCompiler compiler = JavacTool.create();
73+
List<String> options = List.of("-source", Source.DEFAULT.name,
74+
"-target", Target.DEFAULT.name,
75+
"-proc:only",
76+
"--system", "none",
77+
"--module-source-path", args[1],
78+
"--add-modules", Arrays.stream(args)
79+
.skip(2)
80+
.collect(Collectors.joining(",")));
81+
List<String> jlObjectList = List.of("java.lang.Object");
82+
JavacTaskImpl task = (JavacTaskImpl) compiler.getTask(null, null, null, options, jlObjectList, null);
83+
task.enter();
84+
Elements elements = task.getElements();
85+
Deque<String> todo = new ArrayDeque<>();
86+
Arrays.stream(args).skip(2).forEach(todo::add);
87+
88+
todo.add("java.base");
89+
90+
Map<String, Set<String>> modulesAndExports = new TreeMap<>();
91+
92+
while (!todo.isEmpty()) {
93+
String current = todo.removeFirst();
94+
95+
if (modulesAndExports.containsKey(current))
96+
continue;
97+
98+
ModuleSymbol mod = (ModuleSymbol) elements.getModuleElement(current);
99+
100+
if (mod == null) {
101+
throw new IllegalStateException("Missing: " + current);
102+
}
103+
104+
//use the internal structure to avoid unnecesarily completing the symbol using the UsesProvidesVisitor:
105+
modulesAndExports.put(mod.getQualifiedName().toString(),
106+
mod.exports
107+
.stream()
108+
.filter((ExportsDirective ed) -> ed.getTargetModules() == null)
109+
.map((ExportsDirective ed) -> ed.getPackage().getQualifiedName().toString())
110+
.collect(Collectors.toCollection(() -> new TreeSet<>()))
111+
);
112+
for (ModuleElement.RequiresDirective rd : mod.requires) {
113+
if (rd.isTransitive()) {
114+
todo.offerLast(rd.getDependency().getQualifiedName().toString());
115+
}
116+
}
117+
}
118+
119+
Path targetFile = Paths.get(args[0]);
120+
121+
Files.createDirectories(targetFile.getParent());
122+
123+
try (Writer w = Files.newBufferedWriter(targetFile);
124+
PrintWriter out = new PrintWriter(w)) {
125+
for (Entry<String, Set<String>> moduleAndExports : modulesAndExports.entrySet()) {
126+
out.write("module:" + moduleAndExports.getKey());
127+
out.write("\n");
128+
for (String pack : moduleAndExports.getValue()) {
129+
out.write(pack);
130+
out.write("\n");
131+
}
132+
}
133+
}
134+
}
135+
136+
}

‎make/modules/jdk.javadoc/Gendata.gmk‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
#
2+
# Copyright (c) 2015, 2020, Oracle and/or its affiliates. All rights reserved.
3+
# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+
#
5+
# This code is free software; you can redistribute it and/or modify it
6+
# under the terms of the GNU General Public License version 2 only, as
7+
# published by the Free Software Foundation. Oracle designates this
8+
# particular file as subject to the "Classpath" exception as provided
9+
# by Oracle in the LICENSE file that accompanied this code.
10+
#
11+
# This code is distributed in the hope that it will be useful, but WITHOUT
12+
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+
# version 2 for more details (a copy is included in the LICENSE file that
15+
# accompanied this code).
16+
#
17+
# You should have received a copy of the GNU General Public License version
18+
# 2 along with this work; if not, write to the Free Software Foundation,
19+
# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+
#
21+
# Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+
# or visit www.oracle.com if you need additional information or have any
23+
# questions.
24+
#
25+
26+
include JavaCompilation.gmk
27+
include Modules.gmk
28+
29+
################################################################################
30+
31+
# Hook to include the corresponding custom file, if present.
32+
$(eval $(call IncludeCustomExtension, modules/jdk.javadoc/Gendata.gmk))
33+
34+
# This is needed to properly setup DOCS_MODULES.
35+
$(eval $(call ReadImportMetaData))
36+
37+
JAVADOC_MODULES := $(DOCS_MODULES)
38+
39+
# Get the complete module source path:
40+
JAVADOC_MODULESOURCEPATH := $(call GetModuleSrcPath)
41+
42+
CT_DATA_DESCRIPTION += $(TOPDIR)/make/data/symbols/symbols
43+
44+
COMPILECREATESYMBOLS_ADD_EXPORTS := \
45+
--add-exports java.base/jdk.internal=java.compiler.interim,jdk.compiler.interim \
46+
--add-exports jdk.compiler.interim/com.sun.tools.javac.api=ALL-UNNAMED \
47+
--add-exports jdk.compiler.interim/com.sun.tools.javac.code=ALL-UNNAMED \
48+
--add-exports jdk.compiler.interim/com.sun.tools.javac.util=ALL-UNNAMED \
49+
--add-exports jdk.compiler.interim/com.sun.tools.javac.jvm=ALL-UNNAMED \
50+
#
51+
52+
$(eval $(call SetupJavaCompilation, COMPILE_CREATE_SYMBOLS, \
53+
TARGET_RELEASE := $(TARGET_RELEASE_BOOTJDK), \
54+
SRC := $(TOPDIR)/make/langtools/src/classes \
55+
$(TOPDIR)/src/jdk.jdeps/share/classes, \
56+
INCLUDES := build/tools/symbolgenerator com/sun/tools/classfile, \
57+
BIN := $(BUILDTOOLS_OUTPUTDIR)/create_symbols, \
58+
DISABLED_WARNINGS := options, \
59+
JAVAC_FLAGS := \
60+
$(INTERIM_LANGTOOLS_ARGS) \
61+
--patch-module java.base=$(BUILDTOOLS_OUTPUTDIR)/gensrc/java.base.interim \
62+
$(COMPILECREATESYMBOLS_ADD_EXPORTS), \
63+
))
64+
65+
$(SUPPORT_OUTPUTDIR)/javadoc-symbols/symbols: \
66+
$(COMPILE_CREATE_SYMBOLS) \
67+
$(wildcard $(TOPDIR)/make/data/symbols/*) \
68+
$(MODULE_INFOS)
69+
$(RM) -r $(@D)
70+
$(MKDIR) -p $(@D)
71+
$(ECHO) Creating javadoc element list
72+
$(JAVA_SMALL) $(INTERIM_LANGTOOLS_ARGS) \
73+
$(COMPILECREATESYMBOLS_ADD_EXPORTS) \
74+
-classpath $(BUILDTOOLS_OUTPUTDIR)/create_symbols \
75+
build.tools.symbolgenerator.CreateSymbols \
76+
build-javadoc-data \
77+
$(CT_DATA_DESCRIPTION) \
78+
$(JDK_OUTPUTDIR)/modules/jdk.javadoc/jdk/javadoc/internal/doclets/toolkit/resources/releases \
79+
11
80+
$(JAVA_SMALL) $(INTERIM_LANGTOOLS_ARGS) \
81+
$(COMPILECREATESYMBOLS_ADD_EXPORTS) \
82+
-classpath $(BUILDTOOLS_OUTPUTDIR)/create_symbols \
83+
build.tools.symbolgenerator.JavadocElementList \
84+
$(JDK_OUTPUTDIR)/modules/jdk.javadoc/jdk/javadoc/internal/doclets/toolkit/resources/releases/element-list-$(JDK_SOURCE_TARGET_VERSION).txt \
85+
$(JAVADOC_MODULESOURCEPATH) \
86+
$(JAVADOC_MODULES)
87+
$(TOUCH) $@
88+
89+
# Copy ct.sym to the modules libs dir
90+
$(eval $(call SetupCopyFiles, COPY_TO_LIBS, \
91+
FILES := $(SUPPORT_OUTPUTDIR)/javadoc-symbols/*.txt, \
92+
DEST := $(JDK_OUTPUTDIR)/modules/jdk.javadoc/jdk/javadoc/internal/doclets/toolkit/resources/releases, \
93+
))
94+
95+
TARGETS += $(SUPPORT_OUTPUTDIR)/javadoc-symbols/symbols
96+
97+
################################################################################

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

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,7 @@ doclet.package=package
8585
doclet.MalformedURL=Malformed URL: {0}
8686
doclet.File_error=Error reading file: {0}
8787
doclet.URL_error=Error fetching URL: {0}
88+
doclet.Resource_error=Error reading resource: {0}
8889
doclet.see.class_or_package_not_found=Tag {0}: reference not found: {1}
8990
doclet.see.class_or_package_not_accessible=Tag {0}: reference not accessible: {1}
9091
doclet.tag.invalid_usage=invalid usage of tag {0}
@@ -340,8 +341,13 @@ doclet.usage.linkoffline.parameters=\
340341
doclet.usage.linkoffline.description=\
341342
Link to docs at <url1> using package list at <url2>
342343

344+
doclet.usage.link-platform-properties.parameters=\
345+
<url>
346+
doclet.usage.link-platform-properties.description=\
347+
Link to platform documentation URLs declared in properties file at <url>
348+
343349
doclet.usage.excludedocfilessubdir.parameters=\
344-
<name>:..
350+
<name>:...
345351
doclet.usage.excludedocfilessubdir.description=\
346352
Exclude any doc-files subdirectories with given name
347353

@@ -357,7 +363,7 @@ doclet.usage.nodeprecated.description=\
357363
Do not include @deprecated information
358364

359365
doclet.usage.noqualifier.parameters=\
360-
<name1>:<name2>:..
366+
<name1>:<name2>:...
361367
doclet.usage.noqualifier.description=\
362368
Exclude the list of qualifiers from the output
363369

@@ -374,6 +380,9 @@ doclet.usage.no-module-directories.description=\
374380
Do not group files for module documentation into \n\
375381
module-specific directories
376382

383+
doclet.usage.no-platform-links.description=\
384+
Do not generate links to the platform documentation
385+
377386
doclet.usage.notree.description=\
378387
Do not generate class hierarchy
379388

0 commit comments

Comments
 (0)