8238503: Remove unused field and accessor for docLocale from ToolOptions

Reviewed-by: hannesw

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

@@ -368,9 +368,10 @@ private Result begin(List<String> options, Iterable<? extends JavaFileObject> fi
             }
         }
 
-        // locale, doclet and maybe taglet, needs to be determined first
+        // Perform an initial scan of the options to determine the doclet to be used (if any),
+        // so that it may participate in the main round of option processing.
         try {
-            doclet = preprocess(fileManager, options);
+            doclet = preprocess(options);
         } catch (ToolException te) {
             if (!te.result.isOK()) {
                 if (te.message != null) {
@@ -621,21 +622,34 @@ int handleDocletOption(int idx, List<String> args, boolean isToolOption)
         return idx;
     }
 
-    private Doclet preprocess(JavaFileManager jfm, List<String> argv)
+    /**
+     * Performs an initial pass over the options, primarily to determine
+     * the doclet to be used (if any), so that it may participate in the
+     * main round of option decoding. This avoids having to specify that
+     * the options to specify the doclet should appear before any options
+     * that are handled by the doclet.
+     *
+     * The downside of this initial phase is that we have to skip over
+     * unknown options, and assume that we can reliably detect the options
+     * we need to handle.
+     *
+     * @param argv the arguments to be processed
+     * @return the doclet
+     * @throws ToolException if an error occurs initializing the doclet
+     * @throws OptionException if an error occurs while processing an option
+     */
+    private Doclet preprocess(List<String> argv)
             throws ToolException, OptionException {
         // doclet specifying arguments
         String userDocletPath = null;
         String userDocletName = null;
 
-        // taglet specifying arguments, since tagletpath is a doclet
-        // functionality, assume they are repeated and inspect all.
-        List<File> userTagletPath = new ArrayList<>();
-        List<String> userTagletNames = new ArrayList<>();
-
         // Step 1: loop through the args, set locale early on, if found.
         for (int i = 0 ; i < argv.size() ; i++) {
             String arg = argv.get(i);
             if (arg.equals(ToolOptions.DUMP_ON_ERROR)) {
+                // although this option is not needed in order to initialize the doclet,
+                // it is helpful if it is set before trying to initialize the doclet
                 options.setDumpOnError(true);
             } else if (arg.equals(ToolOptions.LOCALE)) {
                 checkOneArg(argv, i++);
@@ -669,12 +683,6 @@ private Doclet preprocess(JavaFileManager jfm, List<String> argv)
                 } else {
                     userDocletPath += File.pathSeparator + argv.get(i);
                 }
-            } else if ("-taglet".equals(arg)) {
-                userTagletNames.add(argv.get(i + 1));
-            } else if ("-tagletpath".equals(arg)) {
-                for (String pathname : argv.get(i + 1).split(File.pathSeparator)) {
-                    userTagletPath.add(new File(pathname));
-                }
             }
         }
 
@@ -724,7 +732,7 @@ private Doclet preprocess(JavaFileManager jfm, List<String> argv)
             }
         }
 
-        if (jdk.javadoc.doclet.Doclet.class.isAssignableFrom(docletClass)) {
+        if (Doclet.class.isAssignableFrom(docletClass)) {
             messager.setLocale(locale);
             try {
                 Object o = docletClass.getConstructor().newInstance();

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

@@ -74,11 +74,6 @@
      */
     private boolean breakIterator = false;
 
-    /**
-     * Argument for command-line option {@code -locale}.
-     */
-    private String docLocale = "";
-
     /**
      * Argument for command-line option {@code --dump-on-error}.
      * Dump stack traces for debugging etc.
@@ -413,9 +408,13 @@ public void process() throws InvalidValueException {
 
             // ----- doclet options -----
 
-            new ToolOption(DOCLET, STANDARD, true), // handled in setDocletInvoker
+            // This option exists so that it is documented in the command-line help.
+            // It is implemented in {@link Start#preprocess}.
+            new ToolOption(DOCLET, STANDARD, true),
 
-            new ToolOption(DOCLET_PATH, STANDARD, true), // handled in setDocletInvoker
+            // This option exists so that it is documented in the command-line help.
+            // It is implemented in {@link Start#preprocess}.
+            new ToolOption(DOCLET_PATH, STANDARD, true),
 
             // ----- selection options -----
 
@@ -540,12 +539,9 @@ public void process() {
                 }
             },
 
-            new ToolOption(LOCALE, STANDARD, true) {
-                @Override
-                public void process(String arg) {
-                    docLocale = arg;
-                }
-            },
+            // This option exists so that it is documented in the command-line help.
+            // It is implemented in {@link Start#preprocess}.
+            new ToolOption(LOCALE, STANDARD, true),
 
             new ToolOption("-Xclasses", HIDDEN) {
                 @Override
@@ -554,12 +550,9 @@ public void process() {
                 }
             },
 
-            new ToolOption(DUMP_ON_ERROR, HIDDEN) {
-                @Override
-                public void process() {
-                    dumpOnError = true;
-                }
-            },
+            // This option exists so that it is documented in the command-line help.
+            // It is implemented in {@link Start#preprocess}.
+            new ToolOption(DUMP_ON_ERROR, HIDDEN),
 
             new ToolOption("--ignore-source-errors", HIDDEN) {
                 @Override
@@ -584,8 +577,9 @@ public void process() throws OptionException {
                 }
             },
 
-            // This option exists only for the purpose of documenting itself.
-            // It's actually implemented by the launcher.
+            // This option exists so that it is documented in the command-line help.
+            // It is actually implemented by the launcher, and can only be used when
+            // invoking javadoc from the launcher.
             new ToolOption(J, STANDARD, true) {
                 @Override
                 public void process() {
@@ -692,13 +686,6 @@ boolean breakIterator() {
         return breakIterator;
     }
 
-    /**
-     * Argument for command-line option {@code -locale}.
-     */
-    String locale() {
-        return docLocale;
-    }
-
     /**
      * Argument for command-line option {@code --dump-on-error}.
      * Dump stack traces for debugging etc.