8258657: Doc build is broken by use of new language features

Reviewed-by: tbell, iris

make/Docs.gmk

@@ -1,4 +1,4 @@
-# Copyright (c) 1997, 2020, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 1997, 2021, 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
@@ -477,7 +477,7 @@ $(eval $(call SetupApiDocsGeneration, REFERENCE_API, \
     SHORT_NAME := $(JAVASE_SHORT_NAME), \
     LONG_NAME := $(JAVASE_LONG_NAME), \
     TARGET_DIR := $(DOCS_REFERENCE_IMAGE_DIR)/api, \
-    JAVADOC_CMD := $(JAVADOC), \
+    JAVADOC_CMD := $(DOCS_REFERENCE_JAVADOC), \
     OPTIONS := $(REFERENCE_OPTIONS), \
     TAGS := $(REFERENCE_TAGS), \
 ))

make/autoconf/boot-jdk.m4

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2011, 2020, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2011, 2021, 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
@@ -606,3 +606,28 @@ AC_DEFUN([BOOTJDK_SETUP_BUILD_JDK],
   AC_SUBST(BUILD_JDK)
   AC_SUBST(EXTERNAL_BUILDJDK)
 ])
+
+# The docs-reference JDK is used to run javadoc for the docs-reference targets.
+# If not set, the reference docs will be built using the interim javadoc.
+AC_DEFUN([BOOTJDK_SETUP_DOCS_REFERENCE_JDK],
+[
+  AC_ARG_WITH(docs-reference-jdk, [AS_HELP_STRING([--with-docs-reference-jdk],
+      [path to JDK to use for building the reference documentation])])
+
+  AC_MSG_CHECKING([for docs-reference JDK])
+  if test "x$with_docs_reference_jdk" != "x"; then
+    DOCS_REFERENCE_JDK="$with_docs_reference_jdk"
+    AC_MSG_RESULT([$DOCS_REFERENCE_JDK])
+    DOCS_REFERENCE_JAVADOC="$DOCS_REFERENCE_JDK/bin/javadoc"
+    if test ! -x "$DOCS_REFERENCE_JAVADOC"; then
+      AC_MSG_ERROR([docs-reference JDK found at $DOCS_REFERENCE_JDK did not contain bin/javadoc])
+    fi
+    UTIL_FIXUP_EXECUTABLE(DOCS_REFERENCE_JAVADOC)
+  else
+    AC_MSG_RESULT([no, using interim javadoc for the docs-reference targets])
+    # By leaving this empty, Docs.gmk will revert to the default interim javadoc
+    DOCS_REFERENCE_JAVADOC=
+  fi
+
+  AC_SUBST(DOCS_REFERENCE_JAVADOC)
+])

make/autoconf/configure.ac

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2011, 2020, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2011, 2021, 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
@@ -144,6 +144,7 @@ JDKVER_SETUP_JDK_VERSION_NUMBERS
 
 BOOTJDK_SETUP_BOOT_JDK
 BOOTJDK_SETUP_BUILD_JDK
+BOOTJDK_SETUP_DOCS_REFERENCE_JDK
 
 ###############################################################################
 #

make/autoconf/spec.gmk.in

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2011, 2020, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2011, 2021, 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
@@ -648,6 +648,8 @@ BUILD_JAVA=@FIXPATH@ $(BUILD_JDK)/bin/java $(BUILD_JAVA_FLAGS)
 BUILD_JAVAC=@FIXPATH@ $(BUILD_JDK)/bin/javac
 BUILD_JAR=@FIXPATH@ $(BUILD_JDK)/bin/jar
 
+DOCS_REFERENCE_JAVADOC := @DOCS_REFERENCE_JAVADOC@
+
 # Interim langtools modules and arguments
 INTERIM_LANGTOOLS_BASE_MODULES := java.compiler jdk.compiler jdk.javadoc
 INTERIM_LANGTOOLS_MODULES := $(addsuffix .interim, $(INTERIM_LANGTOOLS_BASE_MODULES))

make/conf/jib-profiles.js

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2021, 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
@@ -723,8 +723,11 @@ var getJibProfilesProfiles = function (input, common, data) {
             configure_args: concat(
                 "--enable-full-docs",
                 versionArgs(input, common),
-                "--with-build-jdk=" + input.get(buildJdkDep, "home_path")
+                "--with-build-jdk=" + input.get(buildJdkDep, "home_path"),
-                    + (input.build_os == "macosx" ? "/Contents/Home" : "")
+                // Provide an explicit JDK for the docs-reference target to
+                // mimic the running conditions of when it's run for real as
+                // closely as possible.
+                "--with-docs-reference-jdk=" + input.get(buildJdkDep, "home_path")
             ),
             default_make_targets: ["all-docs-bundles"],
             artifacts: {