8304689: Add hidden option to disable external spec page

Reviewed-by: erikj, hannesw

make/Docs.gmk

@@ -1,4 +1,4 @@
-# Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 1997, 2023, 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
@@ -111,14 +111,16 @@ JAVADOC_OPTIONS := -use -keywords -notimestamp \
     -encoding ISO-8859-1 -docencoding UTF-8 -breakiterator \
     -splitIndex --system none -javafx --expand-requires transitive \
     --enable-preview -source $(JDK_SOURCE_TARGET_VERSION) \
-    --override-methods=summary
+    --override-methods=summary \
+    --no-external-specs-page
 
 # The reference options must stay stable to allow for comparisons across the
 # development cycle.
 REFERENCE_OPTIONS := -XDignore.symbol.file=true -use -keywords -notimestamp \
     -encoding ISO-8859-1 -breakiterator -splitIndex --system none \
     --enable-preview -source $(JDK_SOURCE_TARGET_VERSION) \
-    -html5 -javafx --expand-requires transitive
+    -html5 -javafx --expand-requires transitive \
+    --no-external-specs-page
 
 # Should we add DRAFT stamps to the generated javadoc?
 ifeq ($(VERSION_IS_GA), true)

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2023, 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
@@ -154,9 +154,14 @@ public class HtmlConfiguration extends BaseConfiguration {
 
     /**
      * A set of values indicating which conditional pages should be generated.
+     *
      * The set is computed lazily, although values must (obviously) be set before
-     * they are required, such as when deciding whether or not to generate links
-     * to these files in the navigation par, on each page, the help file, and so on.
+     * they are required, such as when deciding whether to generate links
+     * to these files in the navigation bar, on each page, the help file, and so on.
+     *
+     * The value for any page may depend on both command-line options to enable or
+     * disable a page, and on content being found for the page, such as deprecated
+     * items to appear in the summary page of deprecated items.
      */
     public final Set<ConditionalPage> conditionalPages;
 

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2023, 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
@@ -263,7 +263,9 @@ public class HtmlDoclet extends AbstractDoclet {
         }
 
         if (options.createIndex()) {
-            ExternalSpecsWriter.generate(configuration);
+            if (!options.noExternalSpecsPage()){
+                ExternalSpecsWriter.generate(configuration);
+            }
             SystemPropertiesWriter.generate(configuration);
             configuration.mainIndex.addElements();
             IndexBuilder allClassesIndex = new IndexBuilder(configuration, nodeprecated, true);

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2023, 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
@@ -138,6 +138,13 @@ public class HtmlOptions extends BaseOptions {
      */
     private boolean noDeprecatedList = false;
 
+    /**
+     * Argument for command-line option {@code --no-external-spec-page}.
+     * True if command-line option "--no-external-spec-page" is used. Default value is
+     * false.
+     */
+    private boolean noExternalSpecsPage = false;
+
     /**
      * Argument for command-line option {@code -nohelp}.
      * True if command-line option "-nohelp" is used. Default value is false.
@@ -343,6 +350,14 @@ public class HtmlOptions extends BaseOptions {
                     }
                 },
 
+                new Hidden(resources, "--no-external-specs-page") {
+                    @Override
+                    public boolean process(String opt, List<String> args) {
+                        noExternalSpecsPage = true;
+                        return true;
+                    }
+                },
+
                 new Option(resources, "-notree") {
                     @Override
                     public boolean process(String opt,  List<String> args) {
@@ -657,6 +672,15 @@ public class HtmlOptions extends BaseOptions {
         return noDeprecatedList;
     }
 
+    /**
+     * Argument for command-line option {@code --no-external-specs-page}.
+     * True if command-line option "--no-external-specs-page" is used. Default value is
+     * false.
+     */
+    public boolean noExternalSpecsPage() {
+        return noExternalSpecsPage;
+    }
+
     /**
      * Argument for command-line option {@code -nohelp}.
      * True if command-line option "-nohelp" is used. Default value is false.

test/langtools/jdk/javadoc/doclet/testSpecTag/TestSpecTag.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2021, 2023, 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
@@ -23,7 +23,7 @@
 
 /*
  * @test
- * @bug 6251738 8226279 8297802
+ * @bug 6251738 8226279 8297802 8296546
  * @summary JDK-8226279 javadoc should support a new at-spec tag
  * @library /tools/lib ../../lib
  * @modules jdk.javadoc/jdk.javadoc.internal.tool
@@ -456,6 +456,20 @@ public class TestSpecTag extends JavadocTester {
                     .replace("#FILE#", src.resolve("p").resolve("C.java").toString()));
     }
 
+    @Test
+    public void testSuppressSpecPage(Path base) throws IOException {
+        Path src = base.resolve("src");
+        tb.writeJavaFiles(src, "package p; /** @spec http://example.com label */ public class C { }");
+
+        javadoc("-d", base.resolve("out").toString(),
+                "--source-path", src.toString(),
+                "--no-external-specs-page",
+                "p");
+        checkExit(Exit.OK);
+
+        checkFiles(false, "external-specs.html");
+    }
+
     @Test
     public void testCombo(Path base) throws IOException {
         for (LinkKind lk : LinkKind.values()) {