8243396: Add a brief description of argfiles to the javadoc help output

Reviewed-by: prappo

src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/Start.java

@@ -240,7 +240,10 @@ public class Start {
         String primaryName = option.primaryName;
         String parameters;
         if (option.hasArg || primaryName.endsWith(":")) {
-            String sep = primaryName.equals(ToolOptions.J) || primaryName.endsWith(":") ? "" : " ";
+            String sep = primaryName.endsWith(":")
+                    || primaryName.equals(ToolOptions.AT)
+                    || primaryName.equals(ToolOptions.J)
+                    ? "" : " ";
             parameters = sep + option.getParameters(messager);
         } else {
             parameters = "";

src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/ToolOptions.java

@@ -66,6 +66,7 @@ public class ToolOptions {
     static final String DOCLET = "-doclet";
     static final String DOCLET_PATH = "-docletpath";
     static final String DUMP_ON_ERROR = "--dump-on-error";
+    static final String AT = "@";
     static final String J = "-J";
     static final String LOCALE = "-locale";
 
@@ -587,6 +588,17 @@ public class ToolOptions {
                 }
             },
 
+            // This option exists so that it is documented in the command-line help.
+            // It is actually implemented by expanding argv early on during execution,
+            // and can only be used when using the command-line and related interfaces
+            // (i.e. not the javax.tools API).
+            new ToolOption(AT, STANDARD, true) {
+                @Override
+                public void process() {
+                    throw new AssertionError("the @ option is handled separately");
+                }
+            },
+
             new ToolOption("--version", STANDARD) {
                 @Override
                 public void process() throws OptionException {
@@ -648,6 +660,7 @@ public class ToolOptions {
             return "main.opt."
                     + optionName
                         .replaceAll("^-*", "")              // remove leading '-'
+                        .replaceAll("^@", "at")             // handle '@'
                         .replaceAll("[^A-Za-z0-9]+$", "")   // remove trailing non-alphanumeric
                         .replaceAll("[^A-Za-z0-9]", ".")    // replace internal non-alphanumeric
                     + suffix;

src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/resources/javadoc.properties

@@ -32,6 +32,11 @@ main.usage=Usage:\n\
 \    javadoc [options] [packagenames] [sourcefiles] [@files]\n\
 where options include:
 
+main.opt.at.arg=\
+    <file>
+main.opt.at.desc=\
+    Read options and filenames from file
+
 main.opt.public.desc=\
     Show only public types and members. For named modules,\n\
     show exported packages and the module''s API.

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

@@ -0,0 +1,59 @@
+/*
+ * Copyright (c) 2020, 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 8243396
+ * @summary general tests for command-line help
+ * @library ../lib
+ * @modules jdk.javadoc/jdk.javadoc.internal.tool
+ * @build javadoc.tester.*
+ * @run main CommandLineHelpTest
+ */
+
+import java.nio.file.Path;
+
+import javadoc.tester.JavadocTester;
+
+public class CommandLineHelpTest extends JavadocTester {
+    public static void main(String... args) throws Exception {
+        CommandLineHelpTest tester = new CommandLineHelpTest();
+        tester.runTests(m -> new Object[] { Path.of(m.getName()) });
+    }
+
+    @Test
+    public void testStandard(Path base) {
+        javadoc("-d", base.resolve("out").toString(),
+                "--help");
+        checkExit(Exit.OK);
+
+        // check no resources missing
+        checkOutput(Output.OUT, false,
+                "message file broken");
+
+        checkOutput(Output.OUT, true,
+                "@<file>",
+                "-J<flag>");
+    }
+
+}