RFR: JDK-8236949: javadoc -Xdoclint does not accumulate options correctly

[Jonathan Gibbons]

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/