8200363: Add javadoc command line setting to fail on warnings

Reviewed-by: hannesw

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

@@ -436,13 +436,15 @@ private Result begin(List<String> options, Iterable<? extends JavaFileObject> fi
                     fileManager.close();
                 } catch (IOException ignore) {}
             }
-            boolean haveErrorWarnings = messager.hasErrors()
-                    || (this.options.rejectWarnings() && messager.hasWarnings());
-            if (!result.isOK() && !haveErrorWarnings) {
+            if (this.options.rejectWarnings() && messager.hasWarnings()) {
+                error("main.warnings.Werror");
+            }
+            boolean haveErrors = messager.hasErrors();
+            if (!result.isOK() && !haveErrors) {
                 // the doclet failed, but nothing reported, flag it!.
                 error("main.unknown.error");
             }
-            if (haveErrorWarnings && result.isOK()) {
+            if (haveErrors && result.isOK()) {
                 result = ERROR;
             }
             messager.printErrorWarningCounts();

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

@@ -107,8 +107,8 @@
     private List<String> modules = new ArrayList<>();
 
     /**
-     * Argument for command-line option {@code -Xwerror}.
-     * Set by -Xwerror.
+     * Argument for command-line option {@code -Werror}.
+     * Set by -Werror.
      */
     private boolean rejectWarnings = false;
 
@@ -514,13 +514,23 @@ public void process() {
                 }
             },
 
+            // superseded by -Werror, retained for a while for compatibility,
+            // although note that it is an undocumented hidden option, and can
+            // be removed without warning
             new ToolOption("-Xwerror", HIDDEN) {
                 @Override
                 public void process() {
                     rejectWarnings = true;
                 }
             },
 
+            new ToolOption("-Werror", STANDARD) {
+                @Override
+                public void process() {
+                    rejectWarnings = true;
+                }
+            },
+
             // ----- other options -----
 
             new ToolOption("-breakiterator", STANDARD) {
@@ -731,8 +741,8 @@ boolean ignoreSourceErrors() {
     }
 
     /**
-     * Argument for command-line option {@code -Xwerror}.
-     * Set by -Xwerror.
+     * Argument for command-line option {@code -Werror}.
+     * Set by -Werror.
      */
     boolean rejectWarnings() {
         return rejectWarnings;

src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/resources/javadoc.properties

@@ -215,6 +215,9 @@ main.opt.J.desc=\
 main.opt.help.extra.desc=\
     Print a synopsis of nonstandard options and exit
 
+main.opt.Werror.desc=\
+    Report an error if any warnings occur
+
 main.usage.foot=\n\
 GNU-style options may use '=' instead of whitespace to separate the name of an\n\
 option from its value.\n
@@ -251,9 +254,6 @@ main.opt.patch.module.desc=\
     Override or augment a module with classes and resources in\n\
     JAR files or directories
 
-main.opt.Xold.desc=\
-    Invoke the legacy javadoc tool
-
 main.Xusage.foot=\n\
 These options are non-standard and subject to change without notice.
 
@@ -291,7 +291,8 @@ main.illegal_class_name=Illegal class name: "{0}"
 main.illegal_package_name=Illegal package name: "{0}"
 main.illegal_option_value=Illegal option value: "{0}"
 main.file.manager.list=FileManager error listing files: "{0}"
-main.assertion.error=assertion failed: "{0}}"
+main.assertion.error=assertion failed: "{0}"
+main.warnings.Werror=warnings found and -Werror specified
 main.unknown.error=an unknown error has occurred
 main.internal.error=an internal error has occurred
 main.unexpected.exception=an unexpected exception was caught: {0}

test/langtools/jdk/javadoc/tool/testWErrorOption/TestWErrorOption.java

@@ -0,0 +1,104 @@
+/*
+ * 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     8200383
+ * @summary Add javadoc command line setting to fail on warnings
+ * @library /tools/lib ../../lib
+ * @modules jdk.javadoc/jdk.javadoc.internal.tool
+ * @build   toolbox.ToolBox javadoc.tester.*
+ * @run main TestWErrorOption
+ */
+
+import java.io.IOException;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+
+import javadoc.tester.JavadocTester;
+import toolbox.ToolBox;
+
+public class TestWErrorOption extends JavadocTester {
+
+    public static void main(String... args) throws Exception {
+        TestWErrorOption tester = new TestWErrorOption();
+        tester.runTests(m -> new Object[] { Paths.get(m.getName()) });
+    }
+
+    private final ToolBox tb = new ToolBox();
+
+    /** Control test to verify behavior without -Werror. */
+    @Test
+    public void testControl(Path base) throws Exception {
+        generateSrc(base);
+
+        javadoc("-d", base.resolve("out").toString(),
+                "-sourcepath", base.resolve("src").toString(),
+                "-Xdoclint:none",
+                "p");
+        checkExit(Exit.OK);
+        checkOutput(Output.OUT, false,
+                "javadoc: error - warnings found and -Werror specified");
+        checkOutput(Output.OUT, true,
+                "1 warning");
+    }
+
+    @Test
+    public void testWerror(Path base) throws Exception {
+        generateSrc(base);
+
+        javadoc("-d", base.resolve("out").toString(),
+                "-sourcepath", base.resolve("src").toString(),
+                "-Xdoclint:none",
+                "-Werror",
+                "p");
+        checkExit(Exit.ERROR);
+        checkOutput(Output.OUT, true,
+                "testWerror/src/p/C.java:6: warning - @return tag cannot be used in method with void return type.",
+                "javadoc: error - warnings found and -Werror specified\n"
+                + "1 error\n"
+                + "1 warning\n");
+    }
+
+    @Test
+    public void testHelp(Path base) throws Exception {
+        javadoc("-d", base.resolve("out").toString(),
+                "--help");
+        checkExit(Exit.OK);
+        checkOutput(Output.OUT, true,
+                "-Werror       Report an error if any warnings occur\n");
+    }
+
+    private void generateSrc(Path base) throws IOException {
+        Path src = base.resolve("src");
+        tb.writeJavaFiles(src,
+                  "package p;\n"
+                + "public class C {\n"
+                + "  /** Comment.\n"
+                + "   *  @return warning\n"
+                + "   */\n"
+                + "  public void m() { }\n"
+                + "}");
+    }
+}
+