Javadoc tool generates an error instead of a warning for missing references

(Discussed on javadoc-dev mailing list https://mail.openjdk.java.net/pipermail/javadoc-dev/2019-May/001068.html )

Consider this trivial Java code:

public class JavadocTest {

    /**
     * Intentionally uses a throws clause referencing an external
     * library which isn't in the classpath
     * @throws ExternalLibraryException some exception
     */
    public void doSomething() throws ExternalLibraryException {

    }
}

Using javadoc version, that's shipped in Java:

java version "1.8.0_172"
Java(TM) SE Runtime Environment (build 1.8.0_172-b11)
Java HotSpot(TM) 64-Bit Server VM (build 25.172-b11, mixed mode)


when I run the javadoc command:

javadoc JavadocTest.java

the command ends up with an error (and exits with a non-zero exit code):

Constructing Javadoc information...
JavadocTest.java:8: error: cannot find symbol
    public void doSomething() throws ExternalLibraryException {
                                     ^
  symbol: class ExternalLibraryException
  location: class JavadocTest
Standard Doclet version 1.8.0_172
Building tree for all the packages and classes...
Generating ./JavadocTest.html...
JavadocTest.java:6: error: reference not found
     * @throws ExternalLibraryException some exception
       ^
Generating ./package-frame.html...
Generating ./package-summary.html...
Generating ./package-tree.html...
Generating ./constant-values.html...
Building index for all the packages and classes...
Generating ./overview-tree.html...
Generating ./index-all.html...
Generating ./deprecated-list.html...
Building index for all classes...
Generating ./allclasses-frame.html...
Generating ./allclasses-noframe.html...
Generating ./index.html...
Generating ./help-doc.html...
1 error
1 warning

It complains of the missing reference to the "ExternalLibraryException"
which is used in the @throws clause and marks it as an error.

However, reading the documentation of this tool at [1], the text under
the "Javadoc options" states:

"Reports warnings for bad references...

...

Messages may be either warnings or errors, depending on their severity
and the likelihood to cause an error if the generated documentation were
run through a validator. For example, bad references or missing Javadoc
comments do not cause the javadoc command to generate invalid HTML, so
these issues are reported as warnings."

This is in contrast to what I'm seeing in the output of the above
javadoc execution.

A subsequent command to check the exit code of the javadoc process does indeed confirm that it exited with a non-zero exit code:

> echo $?
1

[1] https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javadoc.html#CHDCIBFC