Please review a moderately simple fix to a regression in the way that
javadoc handles doclint options.
The feature was introduced in JDK 8, and at that time, the doclet
options were accumulated in a list.
The regression was introduced when the standard doclet was rewritten in
JDK 9, and perhaps because of the introduction of other new doclint
options, the options were changed to accumulate in a map, with "last one
wins" semantics for like-named options. This is the root cause of this
issue.
The fix is to revert to accumulating options in a list, as originally
intended. In addition, the detection of whether doclint should be
enabled or not is improved, compared to JDK 8, such that doclint is only
enabled if either specific groups or all groups are enabled. Previously,
it would only be disabled if just -Xdoclint:none was specified.
The penance for not writing a better unit test in JDK 8 is to write a
better regression test now. One other test (added in JDK 9) was relying
on the bug, and needed to be updated.
In this changeset ...
HtmlConfiguration.java ... the collection is changed to a list
HtmlOptions ... the options are transformed into doclint options (as
before) and accumulated in the list, but only if they pass the initial
check. There is also some minor cleanup ... the option for
-Xdocrootparent is moved out of the group of doclint options, and some
minor warnings highlighted by the IDE were fixed.
WorkArounds ... the primary change here is better analysis of the
doclint options to determine if doclint should be enabled. Comments are
added, and the "TODO: fix this up correctly" is removed ;-)
The new test uses a source file that will trigger different doclint
diagnostics, depending on which are enabled. It then runs javadoc with
different doclint options to verify that (just) the expected diagnostics
are generated.
-- Jon
JBS: https://bugs.openjdk.java.net/browse/JDK-8236949
Webrev: http://cr.openjdk.java.net/~jjg/8236949/webrev.00/
