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

[Jonathan Gibbons]

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.

The "terminate early" barely applies to javadoc, since we don't have the 
same concept of phases as javac. That being said, there is ...

  * Option decoding
  * Read files (using javac)
  * Another other prep in the tool before handing control to the doclet
  * The doclet

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

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.

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

> jjg at jjg-Precision-T7600:/w/jjg/work/jdk.ref$ 
> ./build/linux-x86_64-server-release/images/jdk/bin/javac -X | grep max
>   -Xmaxerrs <number>           Set the maximum number of errors to print
>   -Xmaxwarns <number>          Set the maximum number of warnings to print
> jjg at jjg-Precision-T7600:/w/jjg/work/jdk.ref$ 
> ./build/linux-x86_64-server-release/images/jdk/bin/javadoc -X | grep max
>     -Xmaxerrs <number>
>                   Set the maximum number of errors to print
>     -Xmaxwarns <number>
>                   Set the maximum number of warnings to print

-- Jon


On 01/17/2020 05:57 AM, Pavel Rappo wrote:
> I like it.
>
> When comparing the wording for the corresponding option for javac I noticed that
> it is more vague than that of the proposed for javadoc:
>
>      -Werror  Terminate compilation if warnings occur (javac)
>      -Werror: treat warnings as if they were errors (proposed for javadoc)
>
> Does the latter preclude lazy behaviour (i.e. the documenting process terminates
> immediately after the first warning occurs)?
>
> It might not be a big deal, especially taking into account that javadoc doesn't
> have options such as:
>
>       -Xmaxerrors number
>                Set the maximum number of errors to print.
>
>         -Xmaxwarns number
>                Set the maximum number of warnings to print.
>
> -Pavel
>
>> On 16 Jan 2020, at 20:13, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
>>
>> Please review a simple CSR to have javadoc support a new option, -Werror, similar to the equivalent javac option.
>>
>> https://bugs.openjdk.java.net/browse/JDK-8237391
>>
>> -- Jon
>>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20200117/8ed1bda3/attachment.htm>