From a282ed392389297604b27379fa15d1f495cbb711 Mon Sep 17 00:00:00 2001 From: Jonathan Gibbons Date: Mon, 3 Jun 2013 17:24:47 -0700 Subject: [PATCH] 8007687: javadoc -X does not include -Xdoclint Reviewed-by: darcy --- .../formats/html/ConfigurationImpl.java | 11 +++ .../html/resources/standard.properties | 85 ++++++++++--------- .../tools/javac/resources/javac.properties | 10 ++- .../classes/com/sun/tools/javadoc/Start.java | 46 +++++----- .../javadoc/resources/javadoc.properties | 60 +++++++------ .../testHelpOption/TestHelpOption.java | 3 +- .../sun/javadoc/testXOption/TestXOption.java | 85 +++++++++++++++++++ 7 files changed, 206 insertions(+), 94 deletions(-) create mode 100644 langtools/test/com/sun/javadoc/testXOption/TestXOption.java diff --git a/langtools/src/share/classes/com/sun/tools/doclets/formats/html/ConfigurationImpl.java b/langtools/src/share/classes/com/sun/tools/doclets/formats/html/ConfigurationImpl.java index 2b37dd66481..5d84c8064db 100644 --- a/langtools/src/share/classes/com/sun/tools/doclets/formats/html/ConfigurationImpl.java +++ b/langtools/src/share/classes/com/sun/tools/doclets/formats/html/ConfigurationImpl.java @@ -324,8 +324,19 @@ public class ConfigurationImpl extends Configuration { option.startsWith("-xdoclint:")) { return 1; } else if (option.equals("-help")) { + // Uugh: first, this should not be hidden inside optionLength, + // and second, we should not be writing directly to stdout. + // But we have no access to a DocErrorReporter, which would + // allow use of reporter.printNotice System.out.println(getText("doclet.usage")); return 1; + } else if (option.equals("-x")) { + // Uugh: first, this should not be hidden inside optionLength, + // and second, we should not be writing directly to stdout. + // But we have no access to a DocErrorReporter, which would + // allow use of reporter.printNotice + System.out.println(getText("doclet.X.usage")); + return 1; } else if (option.equals("-footer") || option.equals("-header") || option.equals("-packagesheader") || diff --git a/langtools/src/share/classes/com/sun/tools/doclets/formats/html/resources/standard.properties b/langtools/src/share/classes/com/sun/tools/doclets/formats/html/resources/standard.properties index f288579d392..9951877f8bc 100644 --- a/langtools/src/share/classes/com/sun/tools/doclets/formats/html/resources/standard.properties +++ b/langtools/src/share/classes/com/sun/tools/doclets/formats/html/resources/standard.properties @@ -186,45 +186,50 @@ doclet.Groupname_already_used=In -group option, groupname already used: {0} doclet.Same_package_name_used=Package name format used twice: {0} doclet.exception_encountered=Exception encountered while processing {1}\n{0} doclet.usage=Provided by Standard doclet:\n\ - -d Destination directory for output files\n\ - -use Create class and package usage pages\n\ - -version Include @version paragraphs\n\ - -author Include @author paragraphs\n\ - -docfilessubdirs Recursively copy doc-file subdirectories\n\ - -splitindex Split index into one file per letter\n\ - -windowtitle Browser window title for the documenation\n\ - -doctitle Include title for the overview page\n\ - -header Include header text for each page\n\ - -footer Include footer text for each page\n\ - -top Include top text for each page\n\ - -bottom Include bottom text for each page\n\ - -link Create links to javadoc output at \n\ - -linkoffline Link to docs at using package list at \n\ - -excludedocfilessubdir :.. Exclude any doc-files subdirectories with given name.\n\ - -group :.. Group specified packages together in overview page\n\ - -nocomment Supress description and tags, generate only declarations.\n\ - -nodeprecated Do not include @deprecated information\n\ - -noqualifier ::... Exclude the list of qualifiers from the output.\n\ - -nosince Do not include @since information\n\ - -notimestamp Do not include hidden time stamp\n\ - -nodeprecatedlist Do not generate deprecated list\n\ - -notree Do not generate class hierarchy\n\ - -noindex Do not generate index\n\ - -nohelp Do not generate help link\n\ - -nonavbar Do not generate navigation bar\n\ - -serialwarn Generate warning about @serial tag\n\ - -tag ::
Specify single argument custom tags\n\ - -taglet The fully qualified name of Taglet to register\n\ - -tagletpath The path to Taglets\n\ - -Xdocrootparent Replaces all appearances of @docRoot followed by /.. in doc comments with \n\ - -charset Charset for cross-platform viewing of generated documentation.\n\ - -helpfile Include file that help link links to\n\ - -linksource Generate source in HTML\n\ - -sourcetab Specify the number of spaces each tab takes up in the source\n\ - -keywords Include HTML meta tags with package, class and member info\n\ - -stylesheetfile File to change style of the generated documentation\n\ - -docencoding Output encoding name - - +\ -d Destination directory for output files\n\ +\ -use Create class and package usage pages\n\ +\ -version Include @version paragraphs\n\ +\ -author Include @author paragraphs\n\ +\ -docfilessubdirs Recursively copy doc-file subdirectories\n\ +\ -splitindex Split index into one file per letter\n\ +\ -windowtitle Browser window title for the documentation\n\ +\ -doctitle Include title for the overview page\n\ +\ -header Include header text for each page\n\ +\ -footer Include footer text for each page\n\ +\ -top Include top text for each page\n\ +\ -bottom Include bottom text for each page\n\ +\ -link Create links to javadoc output at \n\ +\ -linkoffline Link to docs at using package list at \n\ +\ -excludedocfilessubdir :.. Exclude any doc-files subdirectories with given name.\n\ +\ -group :.. Group specified packages together in overview page\n\ +\ -nocomment Suppress description and tags, generate only declarations.\n\ +\ -nodeprecated Do not include @deprecated information\n\ +\ -noqualifier ::... Exclude the list of qualifiers from the output.\n\ +\ -nosince Do not include @since information\n\ +\ -notimestamp Do not include hidden time stamp\n\ +\ -nodeprecatedlist Do not generate deprecated list\n\ +\ -notree Do not generate class hierarchy\n\ +\ -noindex Do not generate index\n\ +\ -nohelp Do not generate help link\n\ +\ -nonavbar Do not generate navigation bar\n\ +\ -serialwarn Generate warning about @serial tag\n\ +\ -tag ::
Specify single argument custom tags\n\ +\ -taglet The fully qualified name of Taglet to register\n\ +\ -tagletpath The path to Taglets\n\ +\ -charset Charset for cross-platform viewing of generated documentation.\n\ +\ -helpfile Include file that help link links to\n\ +\ -linksource Generate source in HTML\n\ +\ -sourcetab Specify the number of spaces each tab takes up in the source\n\ +\ -keywords Include HTML meta tags with package, class and member info\n\ +\ -stylesheetfile File to change style of the generated documentation\n\ +\ -docencoding Specify the character encoding for the output +# L10N: do not localize these words: all none accessibility html missing reference syntax +doclet.X.usage=Provided by standard doclet:\n\ +\ -Xdocrootparent Replaces all appearances of @docRoot followed\n\ +\ by /.. in doc comments with \n\ +\ -Xdoclint Enable recommended checks for problems in javadoc comments\n\ +\ -Xdoclint:(all|none|[-]) \n\ +\ Enable or disable specific checks for problems in javadoc comments,\n\ +\ where is one of accessibility, html, missing, reference, or syntax.\n diff --git a/langtools/src/share/classes/com/sun/tools/javac/resources/javac.properties b/langtools/src/share/classes/com/sun/tools/javac/resources/javac.properties index caf67462a82..f32c2291748 100644 --- a/langtools/src/share/classes/com/sun/tools/javac/resources/javac.properties +++ b/langtools/src/share/classes/com/sun/tools/javac/resources/javac.properties @@ -1,5 +1,5 @@ # -# Copyright (c) 1999, 2012, Oracle and/or its affiliates. All rights reserved. +# Copyright (c) 1999, 2013, 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 @@ -146,11 +146,15 @@ javac.opt.Xlint.suboptlist=\ Enable or disable specific warnings javac.opt.Xdoclint=\ Enable recommended checks for problems in javadoc comments +# L10N: do not localize: all none javac.opt.Xdoclint.subopts = \ - (all|[-])[/] + (all|none|[-])[/] + +# L10N: do not localize: accessibility html missing reference syntax +# L10N: do not localize: public protected package private javac.opt.Xdoclint.custom=\n\ \ Enable or disable specific checks for problems in javadoc comments,\n\ -\ where is one of accessibility, html, reference, or syntax,\n\ +\ where is one of accessibility, html, missing, reference, or syntax,\n\ \ and is one of public, protected, package, or private. javac.opt.Xstdout=\ Redirect standard output diff --git a/langtools/src/share/classes/com/sun/tools/javadoc/Start.java b/langtools/src/share/classes/com/sun/tools/javadoc/Start.java index 4efb9324e26..7cee9aa26e3 100644 --- a/langtools/src/share/classes/com/sun/tools/javadoc/Start.java +++ b/langtools/src/share/classes/com/sun/tools/javadoc/Start.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 2012, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1997, 2013, 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 @@ -156,21 +156,8 @@ public class Start extends ToolOption.Helper { usage(true); } - - /** - * Usage - */ - private void usage(boolean exit) { - // RFE: it would be better to replace the following with code to - // write a header, then help for each option, then a footer. - messager.notice("main.usage"); - - // let doclet print usage information (does nothing on error) - if (docletInvoker != null) { - docletInvoker.optionLength("-help"); - } - - if (exit) exit(); + void usage(boolean exit) { + usage("main.usage", "-help", null, exit); } @Override @@ -178,11 +165,28 @@ public class Start extends ToolOption.Helper { Xusage(true); } - /** - * Usage - */ - private void Xusage(boolean exit) { - messager.notice("main.Xusage"); + void Xusage(boolean exit) { + usage("main.Xusage", "-X", "main.Xusage.foot", exit); + } + + private void usage(String main, String doclet, String foot, boolean exit) { + // RFE: it would be better to replace the following with code to + // write a header, then help for each option, then a footer. + messager.notice(main); + + // let doclet print usage information (does nothing on error) + if (docletInvoker != null) { + // RFE: this is a pretty bad way to get the doclet to show + // help info. Moreover, the output appears on stdout, + // and not on any of the standard streams passed + // to javadoc, and in particular, not to the noticeWriter + // But, to fix this, we need to fix the Doclet API. + docletInvoker.optionLength(doclet); + } + + if (foot != null) + messager.notice(foot); + if (exit) exit(); } diff --git a/langtools/src/share/classes/com/sun/tools/javadoc/resources/javadoc.properties b/langtools/src/share/classes/com/sun/tools/javadoc/resources/javadoc.properties index 4189f6ba7e7..3e384a165de 100644 --- a/langtools/src/share/classes/com/sun/tools/javadoc/resources/javadoc.properties +++ b/langtools/src/share/classes/com/sun/tools/javadoc/resources/javadoc.properties @@ -1,5 +1,5 @@ # -# Copyright (c) 1997, 2012, Oracle and/or its affiliates. All rights reserved. +# Copyright (c) 1997, 2013, 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 @@ -27,35 +27,39 @@ main.errors={0} errors main.error={0} error main.warnings={0} warnings main.warning={0} warning -main.usage=usage: javadoc [options] [packagenames] [sourcefiles] [@files]\n\ - -overview Read overview documentation from HTML file\n\ - -public Show only public classes and members\n\ - -protected Show protected/public classes and members (default)\n\ - -package Show package/protected/public classes and members\n\ - -private Show all classes and members\n\ - -help Display command line options and exit\n\ - -doclet Generate output via alternate doclet\n\ - -docletpath Specify where to find doclet class files\n\ - -sourcepath Specify where to find source files\n\ - -classpath Specify where to find user class files\n\ - -exclude Specify a list of packages to exclude\n\ - -subpackages Specify subpackages to recursively load\n\ - -breakiterator Compute 1st sentence with BreakIterator\n\ - -bootclasspath Override location of class files loaded\n\ -\t\t\t by the bootstrap class loader\n\ - -source Provide source compatibility with specified release\n\ - -extdirs Override location of installed extensions\n\ - -verbose Output messages about what Javadoc is doing\n\ - -locale Locale to be used, e.g. en_US or en_US_WIN\n\ - -encoding Source file encoding name\n\ - -quiet Do not display status messages\n\ - -J Pass directly to the runtime system\n\ - -X Print a synopsis of nonstandard options\n + +main.usage=Usage: javadoc [options] [packagenames] [sourcefiles] [@files]\n\ +\ -overview Read overview documentation from HTML file\n\ +\ -public Show only public classes and members\n\ +\ -protected Show protected/public classes and members (default)\n\ +\ -package Show package/protected/public classes and members\n\ +\ -private Show all classes and members\n\ +\ -help Display command line options and exit\n\ +\ -doclet Generate output via alternate doclet\n\ +\ -docletpath Specify where to find doclet class files\n\ +\ -sourcepath Specify where to find source files\n\ +\ -classpath Specify where to find user class files\n\ +\ -exclude Specify a list of packages to exclude\n\ +\ -subpackages Specify subpackages to recursively load\n\ +\ -breakiterator Compute first sentence with BreakIterator\n\ +\ -bootclasspath Override location of class files loaded\n\ +\ by the bootstrap class loader\n\ +\ -source Provide source compatibility with specified release\n\ +\ -extdirs Override location of installed extensions\n\ +\ -verbose Output messages about what Javadoc is doing\n\ +\ -locale Locale to be used, e.g. en_US or en_US_WIN\n\ +\ -encoding Source file encoding name\n\ +\ -quiet Do not display status messages\n\ +\ -J Pass directly to the runtime system\n\ +\ -X Print a synopsis of nonstandard options and exit\n + main.Xusage=\ - -Xmaxerrs Set the maximum number of errors to print\n\ - -Xmaxwarns Set the maximum number of warnings to print\n\ -\n\ +\ -Xmaxerrs Set the maximum number of errors to print\n\ +\ -Xmaxwarns Set the maximum number of warnings to print\n + +main.Xusage.foot=\ These options are non-standard and subject to change without notice. + main.option.already.seen=The {0} option may be specified no more than once. main.requires_argument=option {0} requires an argument. main.locale_first=option -locale must be first on the command line. diff --git a/langtools/test/com/sun/javadoc/testHelpOption/TestHelpOption.java b/langtools/test/com/sun/javadoc/testHelpOption/TestHelpOption.java index f817596a4fb..e85ffd73339 100644 --- a/langtools/test/com/sun/javadoc/testHelpOption/TestHelpOption.java +++ b/langtools/test/com/sun/javadoc/testHelpOption/TestHelpOption.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2003, 2013, 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 @@ -78,7 +78,6 @@ public class TestHelpOption extends JavadocTester { {STANDARD_OUTPUT, "-tag "}, {STANDARD_OUTPUT, "-taglet "}, {STANDARD_OUTPUT, "-tagletpath "}, - {STANDARD_OUTPUT, "-Xdocrootparent "}, {STANDARD_OUTPUT, "-charset "}, {STANDARD_OUTPUT, "-helpfile "}, {STANDARD_OUTPUT, "-linksource "}, diff --git a/langtools/test/com/sun/javadoc/testXOption/TestXOption.java b/langtools/test/com/sun/javadoc/testXOption/TestXOption.java new file mode 100644 index 00000000000..c66c84d2334 --- /dev/null +++ b/langtools/test/com/sun/javadoc/testXOption/TestXOption.java @@ -0,0 +1,85 @@ +/* + * Copyright (c) 2003, 2013, 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 8007687 + * @summary Make sure that the -X option works properly. + * @library ../lib/ + * @build JavadocTester TestXOption + * @run main TestXOption + */ + +public class TestXOption extends JavadocTester { + + //Test information. + private static final String BUG_ID = "8007687"; + + //Javadoc arguments. + private static final String[] ARGS = new String[] { + "-d", BUG_ID, "-sourcepath", SRC_DIR, "-X", + SRC_DIR + FS + "TestXOption.java" + }; + + private static final String[] ARGS2 = new String[] { + "-d", BUG_ID, "-sourcepath", SRC_DIR, + SRC_DIR + FS + "TestXOption.java" + }; + + private static final String[][] TEST = { + {NOTICE_OUTPUT, "-Xmaxerrs "}, + {NOTICE_OUTPUT, "-Xmaxwarns "}, + {STANDARD_OUTPUT, "-Xdocrootparent "}, + {STANDARD_OUTPUT, "-Xdoclint "}, + {STANDARD_OUTPUT, "-Xdoclint:"}, + }; + private static final String[][] NEGATED_TEST = NO_TEST; + + //The help option should not crash the doclet. + private static final int EXPECTED_EXIT_CODE = 0; + + /** + * The entry point of the test. + * @param args the array of command line arguments. + */ + public static void main(String[] args) { + TestXOption tester = new TestXOption(); + int actualExitCode = run(tester, ARGS, TEST, NEGATED_TEST); + tester.checkExitCode(EXPECTED_EXIT_CODE, actualExitCode); + tester.printSummary(); + } + + /** + * {@inheritDoc} + */ + public String getBugId() { + return BUG_ID; + } + + /** + * {@inheritDoc} + */ + public String getBugName() { + return getClass().getName(); + } +}