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

[Jaikiran Pai]

I just created https://bugs.openjdk.java.net/browse/JDK-8224266 to track
this.

-Jaikiran

On 21/05/19 7:49 AM, Jaikiran Pai wrote:
>
> 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/47b6cb98/attachment-0001.html>