RFR: 8252882: Clean up jdk.javadoc and the related parts of jdk.compiler

[Jonathan Gibbons]

On 9/14/20 7:11 AM, Pavel Rappo wrote:
> I was hoping to use the `assert` facility for the purposes it was designed for. That particular occurrence of `assert`
> as well as others in this pull request are about asserting that **our code** is being correct rather than input being
> correct. The invariants those assertions establish MUST hold regardless of the input.


Assert/assert in all its forms should only be used to assert that our 
code is correct. It is (and always has been) an anti-pattern to use it 
for asserting that input is correct, whether that is user input, illegal 
arguments, etc.

As Jan explained at one point, the use of the Assert class is to better 
manage failures in case our code was incorrect, by failing-fast at 
well-defined, instead of carrying on regardless, until the code fell 
over for downstream reasons.

-- Jon