javadoc (1.8.x) tool generates error for missing reference

[Jonathan Gibbons]

Jaikiran,

Based on the intent of the code, as documented, this is an issue in the 
tool itself.

It should be possible to reference items not on the path, and since that 
would not
cause invalid HTML, it should just be a warning.

-- Jon


On 05/17/2019 08:45 PM, Jaikiran Pai wrote:
> (resending, previous attempt doesn't seem to have made it to the list)
>
> 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)
>
> (on a side note, unlike other Java tools, I couldn't find a way/option
> to print the version of the javadoc tool).
>
> 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.
>
> Is this an error in the tool or is this an error in the documentation of
> the tool?
>
>
> [1]
> https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javadoc.html#CHDCIBFC 
> <https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javadoc.html#CHDCIBFC>
>
>
> -Jaikiran
>
>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190520/258edc75/attachment.html>