8224612: javadoc should better handle empty set of doclet options

Reviewed-by: hannesw

Author: Pavel Rappo

src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/Start.java

@@ -188,8 +188,6 @@ private void showUsage(String headerKey, ToolOption.Kind kind, String footerKey)
 
         // let doclet print usage information
         if (docletClass != null) {
-            String name = doclet.getName();
-            messager.notice("main.doclet.usage.header", name);
             showDocletOptions(kind == ToolOption.Kind.EXTENDED
                     ? Option.Kind.EXTENDED
                     : Option.Kind.STANDARD);
@@ -252,6 +250,13 @@ private void showToolOption(ToolOption option) {
     }
 
     private void showDocletOptions(Option.Kind kind) {
+        String name = doclet.getName();
+        Set<? extends Option> options = getSupportedOptionsOf(doclet);
+        if (options.isEmpty()) {
+            return;
+        }
+        messager.notice("main.doclet.usage.header", name);
+
         Comparator<Doclet.Option> comp = new Comparator<Doclet.Option>() {
             final Collator collator = Collator.getInstance(Locale.US);
             { collator.setStrength(Collator.PRIMARY); }
@@ -262,7 +267,7 @@ public int compare(Doclet.Option o1, Doclet.Option o2) {
             }
         };
 
-        doclet.getSupportedOptions().stream()
+        options.stream()
                 .filter(opt -> opt.getKind() == kind)
                 .sorted(comp)
                 .forEach(this::showDocletOption);
@@ -577,7 +582,7 @@ boolean matches(Doclet.Option option, String arg) {
     int handleDocletOption(int idx, List<String> args, boolean isToolOption)
             throws OptionException {
         if (docletOptions == null) {
-            docletOptions = doclet.getSupportedOptions();
+            docletOptions = getSupportedOptionsOf(doclet);
         }
         String arg = args.get(idx);
         String argBase, argVal;
@@ -623,6 +628,11 @@ int handleDocletOption(int idx, List<String> args, boolean isToolOption)
         return idx;
     }
 
+    private static Set<? extends Option> getSupportedOptionsOf(Doclet doclet) {
+        Set<? extends Option> options = doclet.getSupportedOptions();
+        return options == null ? Set.of() : options;
+    }
+
     /**
      * Performs an initial pass over the options, primarily to determine
      * the doclet to be used (if any), so that it may participate in the

test/langtools/jdk/javadoc/tool/8224612/OptionsTest.java

@@ -0,0 +1,159 @@
+/*
+ * Copyright (c) 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.
+ *
+ * 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.
+ */
+
+/*
+ * @test
+ * @bug 8224612
+ * @key randomness
+ * @library /tools/lib ../../lib
+ * @modules jdk.javadoc/jdk.javadoc.internal.tool
+ * @build javadoc.tester.*
+ * @run main OptionsTest
+ */
+
+import javadoc.tester.JavadocTester;
+import jdk.javadoc.doclet.Doclet;
+import jdk.javadoc.doclet.DocletEnvironment;
+import jdk.javadoc.doclet.Reporter;
+
+import javax.lang.model.SourceVersion;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Locale;
+import java.util.Random;
+import java.util.Set;
+import java.util.TreeSet;
+import java.util.function.Supplier;
+
+public class OptionsTest extends JavadocTester {
+
+    public static void main(String... args) throws Exception {
+        new OptionsTest().runTests(m -> new Object[]{Paths.get(m.getName())});
+    }
+
+    @Test
+    public void testEmptySupportedOptionsDoclet(Path base) {
+        test(EmptySupportedOptionsDoclet.class);
+    }
+
+    private void test(Class<? extends Doclet> _class) {
+        javadoc("-doclet", _class.getName(),
+                "-docletpath", System.getProperty("test.classes", "."),
+                "--help");
+        checkExit(Exit.OK);
+        checkOutput(Output.OUT, false, "javadoc: error - fatal error encountered: java.lang.NullPointerException");
+        checkOutput(Output.OUT, false, "Provided by the %s doclet:".formatted(_class.getSimpleName()));
+    }
+
+    @Test
+    public void testNullSupportedOptionsDoclet(Path base) {
+        test(NullSupportedOptionsDoclet.class);
+    }
+
+    public static final class EmptySupportedOptionsDoclet implements Doclet {
+
+        private final Random random;
+
+        public EmptySupportedOptionsDoclet() {
+            long seed = Long.getLong("jdk.test.lib.random.seed", System.currentTimeMillis());
+            System.out.println("new java.util.Random(" + seed + ")");
+            this.random = new Random(seed);
+        }
+
+        @Override
+        public void init(Locale locale, Reporter reporter) {
+        }
+
+        @Override
+        public String getName() {
+            return getClass().getSimpleName();
+        }
+
+        @Override
+        public Set<? extends Option> getSupportedOptions() {
+            return randomEmptySet();
+        }
+
+        /*
+         * This method is used to check that emptiness of a set is determined
+         * by value (or in this case, by behavior), rather than by reference
+         * (i.e. there's no code like `s == Collections.EMPTY_SET`, etc.)
+         */
+        private Set<? extends Option> randomEmptySet() {
+            List<Supplier<Set<? extends Option>>> emptySets = List.of(
+                    Set::of,
+                    Collections::emptySet,
+                    HashSet::new,
+                    TreeSet::new,
+                    LinkedHashSet::new
+            );
+            int idx = random.nextInt(emptySets.size());
+            return emptySets.get(idx).get();
+        }
+
+        @Override
+        public SourceVersion getSupportedSourceVersion() {
+            return SourceVersion.latestSupported();
+        }
+
+        @Override
+        public boolean run(DocletEnvironment environment) {
+            return true;
+        }
+    }
+
+    /**
+     * An implementation of an otherwise well-behaving Doclet, that returns
+     * {@code null} from {@link #getSupportedOptions}.
+     */
+    public static final class NullSupportedOptionsDoclet implements Doclet {
+
+        @Override
+        public void init(Locale locale, Reporter reporter) {
+        }
+
+        @Override
+        public String getName() {
+            return getClass().getSimpleName();
+        }
+
+        @Override
+        public Set<? extends Option> getSupportedOptions() {
+            return null;
+        }
+
+        @Override
+        public SourceVersion getSupportedSourceVersion() {
+            return SourceVersion.latestSupported();
+        }
+
+        @Override
+        public boolean run(DocletEnvironment environment) {
+            return true;
+        }
+    }
+}