RFR CSR: JDK-8237391 Add -Werror option to javadoc

[Pavel Rappo]

Hi Jon,

> On 17 Jan 2020, at 18:25, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
> 
> Hi Pavel,
> 
> Good feedback.
> 
> The javadoc wording was deliberately more vague, because I couldn't think of anything accurate and more specific to say.  Essentially, we just want to convey/enable one bit of info ... you'll get a non-zero exit code if any warnings occur.

I thought that javac's wording was more vague. The intent is clear though.

> <snip>
> 
> The other reason was because I couldn't think of a good word to replace "compilation".   Any suggestions?

Could (compilation, compiling) map to (documentation, documenting)?
    
    https://www.merriam-webster.com/dictionary/documentation

        1: the act or an instance of furnishing or authenticating with documents

    https://www.merriam-webster.com/dictionary/documenting

> The proposed javadoc text does not preclude lazy behavior; it delegates to the general rules for errors, for which nothing is specified(!) although it is common practice to terminate work "sometime after" the diagnostic occurs. Normally, javac continues to the end of the current phase, since the check of "should I continue" is done between phases.

ok.

> Note that javadoc *does* have -Xmaxerrs and -Xmaxwarns, and (surprisingly?) they are actually in alignment with javac!

Dang! I missed that. Perhaps because I was looking at (sadly, outdated) man
pages, rather than the output of `%tool-name% -X`. In contrast to javadoc's man
page, javac's does provide info about those options.

-Pavel