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

[Jaikiran Pai]

Thank you for the answer, Jon.

I'll file an issue in the JBS later today with the details.

-Jaikiran

On 20/05/19 11:11 PM, Jonathan Gibbons wrote:
>
> 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/20190521/74341e83/attachment-0001.html>