Problem

javadoc can generate warnings. For developers that like to maintain a warning-free code base, it is desirable to be able to treat warnings as errors.

javadoc actually provides such a mechanism, but the option is undocumented and has a non-standard name (-Xwerror) compared to similar options in similar tools (e.g. -Werror in javac and gcc).

Solution

A new option, -Werror will be added, and documented. The old option will be retained (as an undocumented option) for the benefit of any users who may be using it.

Although the name of the option does not conform to the guidelines specified in JEP 293 [1], there is enough precedent of existing usage in similar contexts to justify the use of the name.

Specification

A new option, -Werror is provided.

If the option is present, and if warnings are generated while the tool is executing:

• an error message will also be generated noting that warnings have been produced and that the -Werror option is in effect.

• the individual warnings are not affected: in particular, the individual warnings are not converted to errors.

• if the tool is invoked from the command line, it will exit with a non-zero return code.

• it is unspecified whether the error will cause execution of the tool to terminate prematurely.

In the command-line help, the option is listed in the main group of options (i.e. shown by --help) and not in the extra group of options (i.e. shown by --help-extra or -X).

[1] http://openjdk.java.net/jeps/293