Summary

Allow comma as a separator in a list of values for some option arguments

Problem

Colon (:) is currently used in a few places to separate values in a list of values for the argument of an option. This leads to possible confusion with the path separator, which varies by platform, either : or ;, and which is a semantically different kind of argument.

Solution

Allow comma as the recommended separator, while retaining the ability to use colon, for backwards compatibility.

We cannot remove the ability to use colon without breaking existing uses in scripts and the files, but we can encourage the use of a preferable alternative.

There are four options that currently use colon as a separator. Of these, 3 are genuinely lists, for which comma is appropriate. Of those 3, 2 have no compatibility issues, because the items in the list cannot contain commas. The last option, --excludedocfilessubdir, takes a list of directory names, which theoretically could contain comma in their name, although it would be very unusual to do so. This is deemed an acceptable compatibility risk.

The last option that uses colon is -tag, which takes a structured value, not a list, and so comma is not an obvious replacement. In addition, the first part of the value is a tag name, that can potentially include any characters, and which even supports an escape mechanism using \. The benefits of changing the separator in this case do not outweigh the risks, and so this option is left unchanged, except to ensure the documentation makes clear the separator is always a colon.

Specification

The command-line help for 3 options is changed as follows:

120,121c120,122
<     -excludedocfilessubdir <name>:...
<                   Exclude any doc-files subdirectories with given name
---
>     -excludedocfilessubdir <name>,<name>,...
>                   Exclude any doc-files subdirectories with given name.
>                   ':' can also be used anywhere in the argument as a separator.
124,125c125,127
<     -group <name> <g1>:<g2>...
<                   Group specified elements together in overview page
---
>     -group <name> <g1>,<g2>...
>                   Group specified elements together in overview page.
>                   ':' can also be used anywhere in the argument as a separator.
156,157c158,160
<     -noqualifier <name1>:<name2>:...
<                   Exclude the list of qualifiers from the output
---
>     -noqualifier <name1>,<name2>,...
>                   Exclude the list of qualifiers from the output.
>                   ':' can also be used anywhere in the argument as a separator.

The man page updates include cosmetic updates and clarifications as well:

diff --git a/closed/src/jdk.javadoc/share/man/javadoc.md b/closed/src/jdk.javadoc/share/man/javadoc.md
index 782dc55e4c..14b90e1c16 100644
--- a/closed/src/jdk.javadoc/share/man/javadoc.md
+++ b/closed/src/jdk.javadoc/share/man/javadoc.md
@@ -1,5 +1,5 @@
 ---
-# Copyright (c) 1994, 2021, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 1994, 2022, Oracle and/or its affiliates. All rights reserved.
 #

 title: 'JAVADOC(1) JDK @@VERSION_SHORT@@ | JDK Commands'
@@ -418,6 +418,11 @@ The following options are provided by the standard doclet.

 <span id="option-docfilessubdirs">`-docfilessubdirs`</span>
 :   Recursively copies doc-file subdirectories.
+    Enables deep copying of doc-files directories. Subdirectories and all
+    contents are recursively copied to the destination. For example,
+    the directory `doc-files/example/images` and all of its contents are copied.
+    The [`-excludedocfilessubdir`](#option-excludedocfilessubdir)
+    option can be used to exclude specific subdirectories.

 <span id="option-doctitle">`-doctitle` *html-code*</span>
 :   Specifies the title to place near the top of the overview summary file. The
@@ -428,12 +433,11 @@ The following options are provided by the standard doclet.
     must be escaped. For example,
     `javadoc -doctitle "<b>My Library</b><br>v1.0" com.mypackage`.

-<span id="option-excludedocfilessubdir">`-excludedocfilessubdir` *name*</span>
-:   Excludes any doc files subdirectories with the given name. Enables deep
-    copying of doc-files directories. Subdirectories and all contents are
-    recursively copied to the destination. For example, the directory
-    `doc-files/example/images` and all of its contents are copied. There is
-    also an option to exclude subdirectories.
+<span id="option-excludedocfilessubdir">`-excludedocfilessubdir` *name1*`,`*name2...*</span>
+:   Excludes any subdirectories with the given names
+    when recursively copying doc-file subdirectories.
+    See [`-docfilessubdirs`](#option-docfilessubdirs).
+    For historical reasons, `:` can be used anywhere in the argument as a separator instead of `,`.

 <span id="option-footer">`-footer` *html-code*</span>
 :   Specifies the footer text to be placed at the bottom of each output file.
@@ -442,8 +446,9 @@ The following options are provided by the standard doclet.
     does, the `html-code` value must be enclosed in quotation marks. Use escape
     characters for any internal quotation marks within a footer.

-<span id="option-group">`-group` *namep1*`:`*p2*</span>
+<span id="option-group">`-group` *name* *p1*`,`*p2...*</span>
 :   Group the specified packages together in the Overview page.
+    For historical reasons, `:` can be used as a separator anywhere in the argument instead of `,`.

 <span id="option-header">`-header` *html-code*</span>
 :   Specifies the header text to be placed at the top of each output file. The
@@ -701,9 +706,10 @@ The following options are provided by the standard doclet.
 :   Prevents the generation of links to platform documentation.
     These links are generated by default.

-<span id="option-noqualifier">`-noqualifier` *name1*`:`*name2*...</span>
+<span id="option-noqualifier">`-noqualifier` *name1*`,`*name2...*</span>
 :   Excludes the list of qualifiers from the output. The package name is
     removed from places where class or interface names appear.
+    For historical reasons, `:` can be used anywhere in the argument as a separator instead of `,`.

     The following example omits all package qualifiers: `-noqualifier all`.

@@ -796,7 +802,7 @@ The following options are provided by the standard doclet.
     package containing the snippet, and then searches all the directories in the
     given list.

-<span id="option-sourcetab">`-sourcetab` *tablength*</span>
+<span id="option-sourcetab">`-sourcetab` *tab-length*</span>
 :   Specifies the number of spaces each tab uses in the source.

 <span id="option-spec-base-url">`--spec-base-url` *url*</span>
@@ -816,12 +822,30 @@ The following options are provided by the standard doclet.
     spell-check tag names, it is important to include a `-tag` option for every
     custom tag that is present in the source code, disabling (with `X`) those
     that aren't being output in the current run. The colon (`:`) is always the
-    separator. The `-tag` option outputs the tag heading, *header*, in bold,
+    separator. To include a colon in the tag name, escape it with a backward
+    slash (`\`). The `-tag` option outputs the tag heading, *header*, in bold,
     followed on the next line by the text from its single argument. Similar to
     any block tag, the argument text can contain inline tags, which are also
     interpreted. The output is similar to standard one-argument tags, such as
     the `@return` and `@author` tags. Omitting a *header* value causes the
-    *name* to be the heading.
+    *name* to be the heading.  *locations* is a list of characters specifying
+    the kinds of declarations in which the tag may be used. The following
+    characters may be used, in either uppercase or lowercase:
+
+    * `A`: all declarations
+    * `C`: constructors
+    * `F`: fields
+    * `M`: methods
+    * `O`: the overview page and other documentation files in `doc-files` subdirectories
+    * `P`: packages
+    * `S`: modules
+    * `T`: types (classes and interfaces)
+    * `X`: nowhere: the tag is disabled, and will be ignored
+
+    The order in which tags are given on the command line will be used
+    as the order in which the tags appear in the generated output.
+    You can include standard tags in the order given on the command line
+    by using the `-tag` option with no *locations* or *header*.

 <span id="option-taglet">`-taglet` *class*</span>
 :   Specifies the fully qualified name of the taglet used in generating the