# HG changeset patch # User jjg # Date 1515786092 28800 # Node ID 30243cf1503e747f62856a17dd1ad0eacef8bfab # Parent f6f6d86b90e7bb133cc0f0f026bb491bb8bba5d7 8194955: Warn when default HTML version is used Reviewed-by: ksrini, bpatel diff -r f6f6d86b90e7 -r 30243cf1503e src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlConfiguration.java --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlConfiguration.java Fri Jan 12 14:01:52 2018 +0530 +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlConfiguration.java Fri Jan 12 11:41:32 2018 -0800 @@ -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 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 @@ 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); diff -r f6f6d86b90e7 -r 30243cf1503e src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties Fri Jan 12 14:01:52 2018 +0530 +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties Fri Jan 12 11:41:32 2018 -0800 @@ -384,3 +384,11 @@ 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. diff -r f6f6d86b90e7 -r 30243cf1503e test/langtools/jdk/javadoc/doclet/testHtmlWarning/TestHtmlWarning.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/test/langtools/jdk/javadoc/doclet/testHtmlWarning/TestHtmlWarning.java Fri Jan 12 11:41:32 2018 -0800 @@ -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); + } +} diff -r f6f6d86b90e7 -r 30243cf1503e test/langtools/jdk/javadoc/tool/6958836/Test.java --- a/test/langtools/jdk/javadoc/tool/6958836/Test.java Fri Jan 12 14:01:52 2018 +0530 +++ b/test/langtools/jdk/javadoc/tool/6958836/Test.java Fri Jan 12 11:41:32 2018 -0800 @@ -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 @@ // 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); diff -r f6f6d86b90e7 -r 30243cf1503e test/langtools/jdk/javadoc/tool/6964914/Test.java --- a/test/langtools/jdk/javadoc/tool/6964914/Test.java Fri Jan 12 14:01:52 2018 +0530 +++ b/test/langtools/jdk/javadoc/tool/6964914/Test.java Fri Jan 12 11:41:32 2018 -0800 @@ -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 @@ File testSrc = new File(System.getProperty("test.src")); String[] args = { "-Xdoclint:none", + "-html4", "-source", "8", "-classpath", ".", "-package", diff -r f6f6d86b90e7 -r 30243cf1503e test/langtools/jdk/javadoc/tool/6964914/TestStdDoclet.java --- a/test/langtools/jdk/javadoc/tool/6964914/TestStdDoclet.java Fri Jan 12 14:01:52 2018 +0530 +++ b/test/langtools/jdk/javadoc/tool/6964914/TestStdDoclet.java Fri Jan 12 11:41:32 2018 -0800 @@ -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 @@ cmdArgs.addAll(Arrays.asList( "-classpath", ".", // insulates us from ambient classpath "-Xdoclint:none", + "-html4", "-package", new File(testSrc, thisClassName + ".java").getPath() )); diff -r f6f6d86b90e7 -r 30243cf1503e test/langtools/jdk/javadoc/tool/MaxWarns.java --- a/test/langtools/jdk/javadoc/tool/MaxWarns.java Fri Jan 12 14:01:52 2018 +0530 +++ b/test/langtools/jdk/javadoc/tool/MaxWarns.java Fri Jan 12 11:41:32 2018 -0800 @@ -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 @@ 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(); diff -r f6f6d86b90e7 -r 30243cf1503e test/langtools/jdk/javadoc/tool/QuietOption.java --- a/test/langtools/jdk/javadoc/tool/QuietOption.java Fri Jan 12 14:01:52 2018 +0530 +++ b/test/langtools/jdk/javadoc/tool/QuietOption.java Fri Jan 12 11:41:32 2018 -0800 @@ -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 @@ void run1() throws Exception { List output = doTest(javadoc.getPath(), "-classpath", ".", // insulates us from ambient classpath + "-html4", "-quiet", new File(testSrc, thisClassName + ".java").getPath()); diff -r f6f6d86b90e7 -r 30243cf1503e test/langtools/jdk/javadoc/tool/doclint/DocLintTest.java --- a/test/langtools/jdk/javadoc/tool/doclint/DocLintTest.java Fri Jan 12 14:01:52 2018 +0530 +++ b/test/langtools/jdk/javadoc/tool/doclint/DocLintTest.java Fri Jan 12 11:41:32 2018 -0800 @@ -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 @@ /* 05 */ "}\n"; private final String rawDiags = "-XDrawDiagnostics"; + private final String htmlVersion = "-html4"; private enum Message { // doclint messages @@ -141,66 +142,66 @@ 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.emptyList()); - files = Arrays.asList(new TestJFO("Test.java", code)); + files = List.of(new TestJFO("Test.java", code)); - test(Collections.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)); diff -r f6f6d86b90e7 -r 30243cf1503e test/langtools/tools/javadoc/6964914/TestStdDoclet.java --- a/test/langtools/tools/javadoc/6964914/TestStdDoclet.java Fri Jan 12 14:01:52 2018 +0530 +++ b/test/langtools/tools/javadoc/6964914/TestStdDoclet.java Fri Jan 12 11:41:32 2018 -0800 @@ -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 @@ cmdArgs.add(javadoc.getPath()); cmdArgs.addAll(Arrays.asList( "-classpath", ".", // insulates us from ambient classpath + "-html4", "-Xdoclint:none", "-package", new File(testSrc, thisClassName + ".java").getPath()