8216497: javadoc should auto-link to platform classes

make/CompileInterimLangtools.gmk

@@ -74,7 +74,7 @@ define SetupInterimModule
       EXCLUDE_FILES := $(TOPDIR)/src/$1/share/classes/module-info.java \
           Standard.java, \
       EXTRA_FILES := $(BUILDTOOLS_OUTPUTDIR)/gensrc/$1.interim/module-info.java, \
-      COPY := .gif .png .xml .css .js javax.tools.JavaCompilerTool, \
+      COPY := .gif .png .xml .css .js .txt javax.tools.JavaCompilerTool, \
       BIN := $(BUILDTOOLS_OUTPUTDIR)/interim_langtools_modules/$1.interim, \
       DISABLED_WARNINGS := module options, \
       JAVAC_FLAGS := \

make/CompileJavaModules.gmk

@@ -348,7 +348,7 @@ jdk.dynalink_CLEAN += .properties
 
 ################################################################################
 
-jdk.javadoc_COPY += .xml .css .js .png
+jdk.javadoc_COPY += .xml .css .js .png .txt
 
 ################################################################################
 

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

@@ -143,6 +143,7 @@
 import com.sun.tools.javac.util.Assert;
 import com.sun.tools.javac.util.Context;
 import com.sun.tools.javac.util.Pair;
+import java.util.Optional;
 
 /**
  * A tool for processing the .sym.txt files.
@@ -3820,6 +3821,47 @@ private static AnnotationDescription parseAnnotation(String value, int[] valuePo
     }
     //</editor-fold>
 
+    /**Create sig files for ct.sym reading the classes description from the directory that contains
+     * {@code ctDescriptionFile}, using the file as a recipe to create the sigfiles.
+     */
+    @SuppressWarnings("unchecked")
+    public void createJavadocData(String ctDescriptionFileExtra, String ctDescriptionFile,
+                                  String targetDir, int startVersion) throws IOException {
+        LoadDescriptions data = load(ctDescriptionFileExtra != null ? Paths.get(ctDescriptionFileExtra)
+                                                                    : null,
+                                     Paths.get(ctDescriptionFile));
+
+        Path target = Paths.get(targetDir);
+
+        for (PlatformInput version : data.versions) {
+            int versionNumber = Integer.parseInt(version.version, Character.MAX_RADIX);
+            if (versionNumber < startVersion) {
+                continue;
+            }
+            Path outputFile = target.resolve("element-list-" + versionNumber + ".txt");
+            Files.createDirectories(outputFile.getParent());
+            try (Writer w = Files.newBufferedWriter(outputFile, StandardCharsets.UTF_8)) {
+                Set<ModuleDescription> modules = new TreeSet<>((m1, m2) -> m1.name.compareTo(m2.name));
+                modules.addAll(data.modules.values());
+                for (ModuleDescription module : modules) {
+                    if ("jdk.unsupported".equals(module.name)) {
+                        continue;
+                    }
+                    Optional<ModuleHeaderDescription> header = module.header.stream().filter(h -> h.versions.contains(version.version)).findAny();
+                    if (header.isEmpty()) {
+                        continue;
+                    }
+                    w.write("module:" + module.name);
+                    w.write("\n");
+                    for (String pack : header.get().exports) {
+                        w.write(pack.replace('/', '.'));
+                        w.write("\n");
+                    }
+                }
+            }
+        }
+    }
+
     private static void help() {
         System.err.println("Help...");
     }
@@ -3900,7 +3942,7 @@ public FileVisitResult visitFileFailed(Path file, IOException exc) throws IOExce
                 new CreateSymbols().createIncrementalBaseLine(args[1], args[2], args);
                 break;
             }
-            case "build-ctsym":
+            case "build-ctsym": {
                 String ctDescriptionFileExtra;
                 String ctDescriptionFile;
                 String ctSymLocation;
@@ -3939,6 +3981,39 @@ public FileVisitResult visitFileFailed(Path file, IOException exc) throws IOExce
                                                   currentVersion,
                                                   systemModules);
                 break;
+            }
+            case "build-javadoc-data": {
+                String ctDescriptionFileExtra;
+                String ctDescriptionFile;
+                String targetDir;
+                int startVersion;
+
+                if (args.length == 4) {
+                    ctDescriptionFileExtra = null;
+                    ctDescriptionFile = args[1];
+                    targetDir = args[2];
+                    startVersion = Integer.parseInt(args[3]);
+                } else if (args.length == 5) {
+                    ctDescriptionFileExtra = args[1];
+                    ctDescriptionFile = args[2];
+                    targetDir = args[3];
+                    startVersion = Integer.parseInt(args[4]);
+                } else {
+                    help();
+                    return ;
+                }
+
+                if (startVersion < 9) {
+                    System.err.println("The start version must be at least 9!");
+                    return ;
+                }
+
+                new CreateSymbols().createJavadocData(ctDescriptionFileExtra,
+                                                      ctDescriptionFile,
+                                                      targetDir,
+                                                      startVersion);
+                break;
+            }
         }
     }
 

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

@@ -0,0 +1,136 @@
+/*
+ * Copyright (c) 2017, 2018, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package build.tools.symbolgenerator;
+
+import java.io.IOException;
+import java.io.PrintWriter;
+import java.io.Writer;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.util.ArrayDeque;
+import java.util.Arrays;
+import java.util.Deque;
+import java.util.List;
+import java.util.Set;
+import java.util.stream.Collectors;
+
+import javax.lang.model.element.ModuleElement.ExportsDirective;
+import javax.lang.model.util.Elements;
+import javax.tools.JavaCompiler;
+
+import com.sun.tools.javac.api.JavacTaskImpl;
+import com.sun.tools.javac.api.JavacTool;
+import com.sun.tools.javac.code.Source;
+import com.sun.tools.javac.code.Symbol.ModuleSymbol;
+import com.sun.tools.javac.jvm.Target;
+import java.util.Map;
+import java.util.Map.Entry;
+import java.util.TreeMap;
+import java.util.TreeSet;
+import javax.lang.model.element.ModuleElement;
+
+/**
+ * Generate list of modules and packages in the current release.
+ * Used by the javadoc tool.
+ */
+public class JavadocElementList {
+
+    private static void help() {
+        System.err.println("java JavadocElementList <target-file> <module-source-path> <root-modules>");
+    }
+
+    public static void main(String... args) throws IOException {
+        if (args.length < 2) {
+            help();
+            return ;
+        }
+
+        JavaCompiler compiler = JavacTool.create();
+        List<String> options = List.of("-source", Source.DEFAULT.name,
+                                       "-target", Target.DEFAULT.name,
+                                       "-proc:only",
+                                       "--system", "none",
+                                       "--module-source-path", args[1],
+                                       "--add-modules", Arrays.stream(args)
+                                                              .skip(2)
+                                                              .collect(Collectors.joining(",")));
+        List<String> jlObjectList = List.of("java.lang.Object");
+        JavacTaskImpl task = (JavacTaskImpl) compiler.getTask(null, null, null, options, jlObjectList, null);
+        task.enter();
+        Elements elements = task.getElements();
+        Deque<String> todo = new ArrayDeque<>();
+        Arrays.stream(args).skip(2).forEach(todo::add);
+
+        todo.add("java.base");
+
+        Map<String, Set<String>> modulesAndExports = new TreeMap<>();
+
+        while (!todo.isEmpty()) {
+            String current = todo.removeFirst();
+
+            if (modulesAndExports.containsKey(current))
+                continue;
+
+            ModuleSymbol mod = (ModuleSymbol) elements.getModuleElement(current);
+
+            if (mod == null) {
+                throw new IllegalStateException("Missing: " + current);
+            }
+
+             //use the internal structure to avoid unnecesarily completing the symbol using the UsesProvidesVisitor:
+            modulesAndExports.put(mod.getQualifiedName().toString(),
+                                  mod.exports
+                                     .stream()
+                                     .filter((ExportsDirective ed) -> ed.getTargetModules() == null)
+                                     .map((ExportsDirective ed) -> ed.getPackage().getQualifiedName().toString())
+                                     .collect(Collectors.toCollection(() -> new TreeSet<>()))
+                                  );
+            for (ModuleElement.RequiresDirective rd : mod.requires) {
+                if (rd.isTransitive()) {
+                    todo.offerLast(rd.getDependency().getQualifiedName().toString());
+                }
+            }
+        }
+
+        Path targetFile = Paths.get(args[0]);
+
+        Files.createDirectories(targetFile.getParent());
+
+        try (Writer w = Files.newBufferedWriter(targetFile);
+             PrintWriter out = new PrintWriter(w)) {
+            for (Entry<String, Set<String>> moduleAndExports : modulesAndExports.entrySet()) {
+                out.write("module:" + moduleAndExports.getKey());
+                out.write("\n");
+                for (String pack : moduleAndExports.getValue()) {
+                    out.write(pack);
+                    out.write("\n");
+                }
+            }
+        }
+    }
+
+}

make/modules/jdk.javadoc/Gendata.gmk

@@ -0,0 +1,97 @@
+#
+# Copyright (c) 2015, 2020, Oracle and/or its affiliates. All rights reserved.
+# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+#
+# This code is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License version 2 only, as
+# published by the Free Software Foundation.  Oracle designates this
+# particular file as subject to the "Classpath" exception as provided
+# by Oracle in the LICENSE file that accompanied this code.
+#
+# This code is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# version 2 for more details (a copy is included in the LICENSE file that
+# accompanied this code).
+#
+# You should have received a copy of the GNU General Public License version
+# 2 along with this work; if not, write to the Free Software Foundation,
+# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+# Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+# or visit www.oracle.com if you need additional information or have any
+# questions.
+#
+
+include JavaCompilation.gmk
+include Modules.gmk
+
+################################################################################
+
+# Hook to include the corresponding custom file, if present.
+$(eval $(call IncludeCustomExtension, modules/jdk.javadoc/Gendata.gmk))
+
+# This is needed to properly setup DOCS_MODULES.
+$(eval $(call ReadImportMetaData))
+
+JAVADOC_MODULES := $(DOCS_MODULES)
+
+# Get the complete module source path:
+JAVADOC_MODULESOURCEPATH := $(call GetModuleSrcPath)
+
+CT_DATA_DESCRIPTION += $(TOPDIR)/make/data/symbols/symbols
+
+COMPILECREATESYMBOLS_ADD_EXPORTS := \
+    --add-exports java.base/jdk.internal=java.compiler.interim,jdk.compiler.interim \
+    --add-exports jdk.compiler.interim/com.sun.tools.javac.api=ALL-UNNAMED \
+    --add-exports jdk.compiler.interim/com.sun.tools.javac.code=ALL-UNNAMED \
+    --add-exports jdk.compiler.interim/com.sun.tools.javac.util=ALL-UNNAMED \
+    --add-exports jdk.compiler.interim/com.sun.tools.javac.jvm=ALL-UNNAMED \
+    #
+
+$(eval $(call SetupJavaCompilation, COMPILE_CREATE_SYMBOLS, \
+    TARGET_RELEASE := $(TARGET_RELEASE_BOOTJDK), \
+    SRC := $(TOPDIR)/make/langtools/src/classes \
+        $(TOPDIR)/src/jdk.jdeps/share/classes, \
+    INCLUDES := build/tools/symbolgenerator com/sun/tools/classfile, \
+    BIN := $(BUILDTOOLS_OUTPUTDIR)/create_symbols, \
+    DISABLED_WARNINGS := options, \
+    JAVAC_FLAGS := \
+        $(INTERIM_LANGTOOLS_ARGS) \
+        --patch-module java.base=$(BUILDTOOLS_OUTPUTDIR)/gensrc/java.base.interim \
+        $(COMPILECREATESYMBOLS_ADD_EXPORTS), \
+))
+
+$(SUPPORT_OUTPUTDIR)/javadoc-symbols/symbols: \
+    $(COMPILE_CREATE_SYMBOLS) \
+    $(wildcard $(TOPDIR)/make/data/symbols/*) \
+    $(MODULE_INFOS)
+	$(RM) -r $(@D)
+	$(MKDIR) -p $(@D)
+	$(ECHO) Creating javadoc element list
+	$(JAVA_SMALL) $(INTERIM_LANGTOOLS_ARGS) \
+	    $(COMPILECREATESYMBOLS_ADD_EXPORTS) \
+	    -classpath $(BUILDTOOLS_OUTPUTDIR)/create_symbols \
+	    build.tools.symbolgenerator.CreateSymbols \
+	    build-javadoc-data \
+	    $(CT_DATA_DESCRIPTION) \
+	    $(JDK_OUTPUTDIR)/modules/jdk.javadoc/jdk/javadoc/internal/doclets/toolkit/resources/releases \
+	    11
+	$(JAVA_SMALL) $(INTERIM_LANGTOOLS_ARGS) \
+	    $(COMPILECREATESYMBOLS_ADD_EXPORTS) \
+	    -classpath $(BUILDTOOLS_OUTPUTDIR)/create_symbols \
+	    build.tools.symbolgenerator.JavadocElementList \
+	    $(JDK_OUTPUTDIR)/modules/jdk.javadoc/jdk/javadoc/internal/doclets/toolkit/resources/releases/element-list-$(JDK_SOURCE_TARGET_VERSION).txt \
+	    $(JAVADOC_MODULESOURCEPATH) \
+	    $(JAVADOC_MODULES)
+	$(TOUCH) $@
+
+# Copy ct.sym to the modules libs dir
+$(eval $(call SetupCopyFiles, COPY_TO_LIBS, \
+    FILES := $(SUPPORT_OUTPUTDIR)/javadoc-symbols/*.txt, \
+    DEST := $(JDK_OUTPUTDIR)/modules/jdk.javadoc/jdk/javadoc/internal/doclets/toolkit/resources/releases, \
+))
+
+TARGETS += $(SUPPORT_OUTPUTDIR)/javadoc-symbols/symbols
+
+################################################################################

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

@@ -85,6 +85,7 @@ doclet.package=package
 doclet.MalformedURL=Malformed URL: {0}
 doclet.File_error=Error reading file: {0}
 doclet.URL_error=Error fetching URL: {0}
+doclet.Resource_error=Error reading resource: {0}
 doclet.see.class_or_package_not_found=Tag {0}: reference not found: {1}
 doclet.see.class_or_package_not_accessible=Tag {0}: reference not accessible: {1}
 doclet.tag.invalid_usage=invalid usage of tag {0}
@@ -340,8 +341,13 @@ doclet.usage.linkoffline.parameters=\
 doclet.usage.linkoffline.description=\
     Link to docs at <url1> using package list at <url2>
 
+doclet.usage.link-platform-properties.parameters=\
+    <url>
+doclet.usage.link-platform-properties.description=\
+    Link to platform documentation URLs declared in properties file at <url>
+
 doclet.usage.excludedocfilessubdir.parameters=\
-    <name>:..
+    <name>:...
 doclet.usage.excludedocfilessubdir.description=\
     Exclude any doc-files subdirectories with given name
 
@@ -357,7 +363,7 @@ doclet.usage.nodeprecated.description=\
     Do not include @deprecated information
 
 doclet.usage.noqualifier.parameters=\
-    <name1>:<name2>:..
+    <name1>:<name2>:...
 doclet.usage.noqualifier.description=\
     Exclude the list of qualifiers from the output
 
@@ -374,6 +380,9 @@ doclet.usage.no-module-directories.description=\
     Do not group files for module documentation into \n\
     module-specific directories
 
+doclet.usage.no-platform-links.description=\
+    Do not generate links to the platform documentation
+
 doclet.usage.notree.description=\
     Do not generate class hierarchy