8194955: Warn when default HTML version is used

Reviewed-by: ksrini, bpatel

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 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
@@ -204,9 +204,10 @@ public class HtmlConfiguration extends BaseConfiguration {
     public boolean frames = true;
 
     /**
-     * This is the HTML version of the generated pages. HTML 4.01 is the default output version.
+     * This is the HTML version of the generated pages.
+     * The default value is determined later.
      */
-    public HtmlVersion htmlVersion = HtmlVersion.HTML4;
+    public HtmlVersion htmlVersion = null;
 
     /**
      * Collected set of doclint options
@@ -298,6 +299,12 @@ public class HtmlConfiguration extends BaseConfiguration {
         if (!generalValidOptions()) {
             return false;
         }
+
+        if (htmlVersion == null) {
+            reporter.print(WARNING, getText("doclet.HTML_version_not_specified", helpfile));
+            htmlVersion = HtmlVersion.HTML4;
+        }
+
         // check if helpfile exists
         if (!helpfile.isEmpty()) {
             DocFile help = DocFile.createFileForInput(this, helpfile);

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

@@ -384,3 +384,11 @@ doclet.usage.xdoclint-package.description=\
     name prefix followed by .*, which expands to all sub-packages\n\
     of the given package. Prefix the package specifier with - to\n\
     disable checks for the specified packages.
+
+# L10N: do not localize the option names -html4 and -html5
+doclet.HTML_version_not_specified=\
+    You have not specified the version of HTML to use.\n\
+    The default is currently HTML 4.01, but this will change to HTML5\n\
+    in a future release. To suppress this warning, please specify the\n\
+    version of HTML used in your documentation comments and to be\n\
+    generated by this doclet, using the -html4 or -html5 options.

test/langtools/jdk/javadoc/doclet/testHtmlWarning/TestHtmlWarning.java

@@ -0,0 +1,81 @@
+/*
+ * Copyright (c) 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.
+ *
+ * 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 8194955
+ * @summary Warn when default HTML version is used.
+ * @library ../lib
+ * @modules jdk.javadoc/jdk.javadoc.internal.tool
+ * @build JavadocTester
+ * @run main TestHtmlWarning
+ */
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.util.List;
+
+public class TestHtmlWarning extends JavadocTester {
+
+    public static void main(String... args) throws Exception {
+        Files.write(testFile,
+                List.of("/** Comment. */", "public class C { }"));
+
+        TestHtmlWarning tester = new TestHtmlWarning();
+        tester.runTests();
+    }
+
+    private static final Path testFile = Paths.get("C.java");
+    private static final String warning =
+        "javadoc: warning - You have not specified the version of HTML to use.";
+
+    @Test
+    void testHtml4() {
+        javadoc("-d", "out-4",
+                "-html4",
+                testFile.toString());
+        checkExit(Exit.OK);
+
+        checkOutput(Output.OUT, false, warning);
+    }
+
+    @Test
+    void testHtml5() {
+        javadoc("-d", "out-5",
+                "-html5",
+                testFile.toString());
+        checkExit(Exit.OK);
+
+        checkOutput(Output.OUT, false, warning);
+    }
+
+    @Test
+    void testDefault() {
+        javadoc("-d", "out-default",
+                testFile.toString());
+        checkExit(Exit.OK);
+
+        checkOutput(Output.OUT, true, warning);
+    }
+}

test/langtools/jdk/javadoc/tool/6958836/Test.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 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
@@ -63,6 +63,7 @@ public class Test {
         // For some reason, this must be the first option when used.
         opts.addAll(list("-locale", "en_US"));
         opts.add("-Xdoclint:none");
+        opts.add("-html4");
         opts.addAll(list("-classpath", System.getProperty("test.src")));
         opts.addAll(list("-d", testOutDir.getPath()));
         opts.addAll(testOpts);

test/langtools/jdk/javadoc/tool/6964914/Test.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 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
@@ -47,6 +47,7 @@ public class Test {
         File testSrc = new File(System.getProperty("test.src"));
         String[] args = {
             "-Xdoclint:none",
+            "-html4",
             "-source", "8",
             "-classpath", ".",
             "-package",

test/langtools/jdk/javadoc/tool/6964914/TestStdDoclet.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 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
@@ -58,6 +58,7 @@ public class TestStdDoclet {
         cmdArgs.addAll(Arrays.asList(
                 "-classpath", ".", // insulates us from ambient classpath
                 "-Xdoclint:none",
+                "-html4",
                 "-package",
                 new File(testSrc, thisClassName + ".java").getPath()
         ));

test/langtools/jdk/javadoc/tool/MaxWarns.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2013, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2013, 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
@@ -75,7 +75,7 @@ public class MaxWarns {
     String javadoc(File f) {
         StringWriter sw = new StringWriter();
         PrintWriter pw = new PrintWriter(sw);
-        String[] args = { "-Xdoclint:none", "-d", "api", f.getPath() };
+        String[] args = { "-Xdoclint:none", "-html4", "-d", "api", f.getPath() };
         int rc = jdk.javadoc.internal.tool.Main.execute(args, pw);
         pw.flush();
         return sw.toString();

test/langtools/jdk/javadoc/tool/QuietOption.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 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
@@ -62,6 +62,7 @@ public class QuietOption {
     void run1() throws Exception {
         List<String> output = doTest(javadoc.getPath(),
                 "-classpath", ".", // insulates us from ambient classpath
+                "-html4",
                 "-quiet",
                 new File(testSrc, thisClassName + ".java").getPath());
 

test/langtools/jdk/javadoc/tool/doclint/DocLintTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 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
@@ -92,6 +92,7 @@ public class DocLintTest {
         /* 05 */    "}\n";
 
     private final String rawDiags = "-XDrawDiagnostics";
+    private final String htmlVersion = "-html4";
 
     private enum Message {
         // doclint messages
@@ -141,66 +142,66 @@ public class DocLintTest {
         javadoc = ToolProvider.getSystemDocumentationTool();
         fm = javadoc.getStandardFileManager(null, null, null);
         try {
-            fm.setLocation(StandardLocation.CLASS_OUTPUT, Arrays.asList(new File(".")));
+            fm.setLocation(StandardLocation.CLASS_OUTPUT, List.of(new File(".")));
             fm.setLocation(StandardLocation.CLASS_PATH, Collections.<File>emptyList());
-            files = Arrays.asList(new TestJFO("Test.java", code));
+            files = List.of(new TestJFO("Test.java", code));
 
-            test(Collections.<String>emptyList(),
+            test(List.of(htmlVersion),
                     Main.Result.ERROR,
                     EnumSet.of(Message.DL_ERR9A, Message.DL_WRN12A));
 
-            test(Arrays.asList(rawDiags),
+            test(List.of(htmlVersion, rawDiags),
                     Main.Result.ERROR,
                     EnumSet.of(Message.DL_ERR9, Message.DL_WRN12));
 
-//            test(Arrays.asList("-Xdoclint:none"),
+//            test(List.of("-Xdoclint:none"),
 //                    Main.Result.OK,
 //                    EnumSet.of(Message.JD_WRN10, Message.JD_WRN13));
 
-            test(Arrays.asList(rawDiags, "-Xdoclint"),
+            test(List.of(htmlVersion, rawDiags, "-Xdoclint"),
                     Main.Result.ERROR,
                     EnumSet.of(Message.DL_ERR9, Message.DL_WRN12));
 
-            test(Arrays.asList(rawDiags, "-Xdoclint:all/public"),
+            test(List.of(htmlVersion, rawDiags, "-Xdoclint:all/public"),
                     Main.Result.ERROR,
                     EnumSet.of(Message.OPT_BADQUAL));
 
-            test(Arrays.asList(rawDiags, "-Xdoclint:all", "-public"),
+            test(List.of(htmlVersion, rawDiags, "-Xdoclint:all", "-public"),
                     Main.Result.OK,
                     EnumSet.of(Message.DL_WRN12));
 
-            test(Arrays.asList(rawDiags, "-Xdoclint:syntax"),
+            test(List.of(htmlVersion, rawDiags, "-Xdoclint:syntax"),
                     Main.Result.OK,
                     EnumSet.of(Message.DL_WRN12));
 
-            test(Arrays.asList(rawDiags, "-private"),
+            test(List.of(htmlVersion, rawDiags, "-private"),
                     Main.Result.ERROR,
                     EnumSet.of(Message.DL_ERR6, Message.DL_ERR9, Message.DL_WRN12));
 
-            test(Arrays.asList(rawDiags, "-Xdoclint:syntax", "-private"),
+            test(List.of(htmlVersion, rawDiags, "-Xdoclint:syntax", "-private"),
                     Main.Result.ERROR,
                     EnumSet.of(Message.DL_ERR6, Message.DL_WRN12));
 
-            test(Arrays.asList(rawDiags, "-Xdoclint:reference"),
+            test(List.of(htmlVersion, rawDiags, "-Xdoclint:reference"),
                     Main.Result.ERROR,
                     EnumSet.of(Message.DL_ERR9));
 
-            test(Arrays.asList(rawDiags, "-Xdoclint:badarg"),
+            test(List.of(htmlVersion, rawDiags, "-Xdoclint:badarg"),
                     Main.Result.ERROR,
                     EnumSet.of(Message.OPT_BADARG));
 
-            files = Arrays.asList(new TestJFO("p1/P1Test.java", p1Code),
+            files = List.of(new TestJFO("p1/P1Test.java", p1Code),
                                   new TestJFO("p2/P2Test.java", p2Code));
 
-            test(Arrays.asList(rawDiags),
+            test(List.of(htmlVersion, rawDiags),
                     Main.Result.ERROR,
                     EnumSet.of(Message.DL_ERR_P1TEST, Message.DL_ERR_P2TEST));
 
-            test(Arrays.asList(rawDiags, "-Xdoclint/package:p1"),
+            test(List.of(htmlVersion, rawDiags, "-Xdoclint/package:p1"),
                     Main.Result.ERROR,
                     EnumSet.of(Message.DL_ERR_P1TEST));
 
-            test(Arrays.asList(rawDiags, "-Xdoclint/package:*p"),
+            test(List.of(htmlVersion, rawDiags, "-Xdoclint/package:*p"),
                     Main.Result.ERROR,
                     EnumSet.of(Message.OPT_BADPACKAGEARG));
 

test/langtools/tools/javadoc/6964914/TestStdDoclet.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 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
@@ -57,6 +57,7 @@ public class TestStdDoclet {
         cmdArgs.add(javadoc.getPath());
         cmdArgs.addAll(Arrays.asList(
                 "-classpath", ".", // insulates us from ambient classpath
+                "-html4",
                 "-Xdoclint:none",
                 "-package",
                 new File(testSrc, thisClassName + ".java").getPath()