archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-09-15 08:34:30 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8194955: Warn when default HTML version is used

Browse source 
Reviewed-by: ksrini, bpatel
This commit is contained in:
Jonathan Gibbons 2018-01-12 11:41:32 -08:00
parent 62777c86cd
commit 372bc7a281
10 changed files with 130 additions and 28 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -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);

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

@ -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.

81
test/langtools/jdk/javadoc/doclet/testHtmlWarning/TestHtmlWarning.java Normal file
View file

@ -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);
}
}

3
test/langtools/jdk/javadoc/tool/6958836/Test.java
View file

@ -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);

3
test/langtools/jdk/javadoc/tool/6964914/Test.java
View file

@ -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",

3
test/langtools/jdk/javadoc/tool/6964914/TestStdDoclet.java
View file

@ -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()
));

4
test/langtools/jdk/javadoc/tool/MaxWarns.java
View file

@ -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();

3
test/langtools/jdk/javadoc/tool/QuietOption.java
View file

@ -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());

37
test/langtools/jdk/javadoc/tool/doclint/DocLintTest.java
View file

@ -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));

3
test/langtools/tools/javadoc/6964914/TestStdDoclet.java
View file

@ -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()