8007687: javadoc -X does not include -Xdoclint

Reviewed-by: darcy

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") ||

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 <directory>                    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 <text>               Browser window title for the documenation\n\
-  -doctitle <html-code>             Include title for the overview page\n\
-  -header <html-code>               Include header text for each page\n\
-  -footer <html-code>               Include footer text for each page\n\
-  -top    <html-code>               Include top text for each page\n\
-  -bottom <html-code>               Include bottom text for each page\n\
-  -link <url>                       Create links to javadoc output at <url>\n\
-  -linkoffline <url> <url2>         Link to docs at <url> using package list at <url2>\n\
-  -excludedocfilessubdir <name1>:.. Exclude any doc-files subdirectories with given name.\n\
-  -group <name> <p1>:<p2>..         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 <name1>:<name2>:...  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 <name>:<locations>:<header>  Specify single argument custom tags\n\
-  -taglet                           The fully qualified name of Taglet to register\n\
-  -tagletpath                       The path to Taglets\n\
-  -Xdocrootparent <url>             Replaces all appearances of @docRoot followed by /.. in doc comments with <url>\n\
-  -charset <charset>                Charset for cross-platform viewing of generated documentation.\n\
-  -helpfile <file>                  Include file that help link links to\n\
-  -linksource                       Generate source in HTML\n\
-  -sourcetab <tab length>           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 <path>            File to change style of the generated documentation\n\
-  -docencoding <name>               Output encoding name
-
-
+\  -d <directory>                   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 <text>              Browser window title for the documentation\n\
+\  -doctitle <html-code>            Include title for the overview page\n\
+\  -header <html-code>              Include header text for each page\n\
+\  -footer <html-code>              Include footer text for each page\n\
+\  -top    <html-code>              Include top text for each page\n\
+\  -bottom <html-code>              Include bottom text for each page\n\
+\  -link <url>                      Create links to javadoc output at <url>\n\
+\  -linkoffline <url> <url2>        Link to docs at <url> using package list at <url2>\n\
+\  -excludedocfilessubdir <name1>:.. Exclude any doc-files subdirectories with given name.\n\
+\  -group <name> <p1>:<p2>..        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 <name1>:<name2>:... 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 <name>:<locations>:<header> Specify single argument custom tags\n\
+\  -taglet                          The fully qualified name of Taglet to register\n\
+\  -tagletpath                      The path to Taglets\n\
+\  -charset <charset>               Charset for cross-platform viewing of generated documentation.\n\
+\  -helpfile <file>                 Include file that help link links to\n\
+\  -linksource                      Generate source in HTML\n\
+\  -sourcetab <tab length>          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 <path>           File to change style of the generated documentation\n\
+\  -docencoding <name>              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 <url>            Replaces all appearances of @docRoot followed\n\
+\                                   by /.. in doc comments with <url>\n\
+\  -Xdoclint                        Enable recommended checks for problems in javadoc comments\n\
+\  -Xdoclint:(all|none|[-]<group>) \n\
+\        Enable or disable specific checks for problems in javadoc comments,\n\
+\        where <group> is one of accessibility, html, missing, reference, or syntax.\n

src/share/classes/com/sun/tools/javac/resources/javac.properties

 #
-# 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|[-]<group>)[/<access>]
+    (all|none|[-]<group>)[/<access>]
+
+# 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 <group> is one of accessibility, html, reference, or syntax,\n\
+\        where <group> is one of accessibility, html, missing, reference, or syntax,\n\
 \        and <access> is one of public, protected, package, or private.
 javac.opt.Xstdout=\
     Redirect standard output

src/share/classes/com/sun/tools/javadoc/Start.java

 /*
- * 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,33 +156,37 @@ public class Start extends ToolOption.Helper {
         usage(true);
     }
 
+    void usage(boolean exit) {
+        usage("main.usage", "-help", null, exit);
+    }
 
-    /**
-     * Usage
-     */
-    private void usage(boolean exit) {
+    @Override
+    void Xusage() {
+        Xusage(true);
+    }
+
+    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.usage");
+        messager.notice(main);
 
         // let doclet print usage information (does nothing on error)
         if (docletInvoker != null) {
-            docletInvoker.optionLength("-help");
+            // RFE: this is a pretty bad way to get the doclet to show
+            // help info. Moreover, the output appears on stdout,
+            // and <i>not</i> 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 (exit) exit();
-    }
-
-    @Override
-    void Xusage() {
-        Xusage(true);
-    }
+        if (foot != null)
+            messager.notice(foot);
 
-    /**
-     * Usage
-     */
-    private void Xusage(boolean exit) {
-        messager.notice("main.Xusage");
         if (exit) exit();
     }
 

src/share/classes/com/sun/tools/javadoc/resources/javadoc.properties

 #
-# 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 <file>          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 <class>           Generate output via alternate doclet\n\
-  -docletpath <path>        Specify where to find doclet class files\n\
-  -sourcepath <pathlist>    Specify where to find source files\n\
-  -classpath <pathlist>     Specify where to find user class files\n\
-  -exclude <pkglist>        Specify a list of packages to exclude\n\
-  -subpackages <subpkglist> Specify subpackages to recursively load\n\
-  -breakiterator            Compute 1st sentence with BreakIterator\n\
-  -bootclasspath <pathlist> Override location of class files loaded\n\
-\t\t\t  by the bootstrap class loader\n\
-  -source <release>         Provide source compatibility with specified release\n\
-  -extdirs <dirlist>        Override location of installed extensions\n\
-  -verbose                  Output messages about what Javadoc is doing\n\
-  -locale <name>            Locale to be used, e.g. en_US or en_US_WIN\n\
-  -encoding <name>          Source file encoding name\n\
-  -quiet                    Do not display status messages\n\
-  -J<flag>                  Pass <flag> directly to the runtime system\n\
-  -X                        Print a synopsis of nonstandard options\n
+
+main.usage=Usage: javadoc [options] [packagenames] [sourcefiles] [@files]\n\
+\  -overview <file>                 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 <class>                  Generate output via alternate doclet\n\
+\  -docletpath <path>               Specify where to find doclet class files\n\
+\  -sourcepath <pathlist>           Specify where to find source files\n\
+\  -classpath <pathlist>            Specify where to find user class files\n\
+\  -exclude <pkglist>               Specify a list of packages to exclude\n\
+\  -subpackages <subpkglist>        Specify subpackages to recursively load\n\
+\  -breakiterator                   Compute first sentence with BreakIterator\n\
+\  -bootclasspath <pathlist>        Override location of class files loaded\n\
+\                                   by the bootstrap class loader\n\
+\  -source <release>                Provide source compatibility with specified release\n\
+\  -extdirs <dirlist>               Override location of installed extensions\n\
+\  -verbose                         Output messages about what Javadoc is doing\n\
+\  -locale <name>                   Locale to be used, e.g. en_US or en_US_WIN\n\
+\  -encoding <name>                 Source file encoding name\n\
+\  -quiet                           Do not display status messages\n\
+\  -J<flag>                         Pass <flag> directly to the runtime system\n\
+\  -X                               Print a synopsis of nonstandard options and exit\n
+
 main.Xusage=\
-  -Xmaxerrs <number>        Set the maximum number of errors to print\n\
-  -Xmaxwarns <number>       Set the maximum number of warnings to print\n\
-\n\
+\  -Xmaxerrs <number>               Set the maximum number of errors to print\n\
+\  -Xmaxwarns <number>              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.

test/com/sun/javadoc/testHelpOption/TestHelpOption.java

 /*
- * 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 "},

test/com/sun/javadoc/testXOption/TestXOption.java

+/*
+ * 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();
+    }
+}