RFR: 8287397 : Print top-level exception when snippet fails to read file

[Jonathan Gibbons]

On Thu, 26 May 2022 23:29:59 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> When using a snippet as follows (on Windows): `{@snippet file=baz\Baz.java }`, javadoc prints the error:
>> 
>> src\foo\foo\Foo.java:14: error: Error reading file: baz\Baz.java
>> {@snippet file=baz\Baz.java }
>>           ^
>>         (null)
>> 
>> 
>> which is unhelpful. So rather than printing the exception's cause (which is `null` in the example above), it seems better to print the top-level exception itself.
>> 
>> PS: I'll need help from someone to create a JBS issue & sponsor this PR
>
> @anthonyvdotbe You need to change the PR summary by inserting `8287397` (the JBS issue number) at the beginning.
> 
>    8287397 : Print top-level exception when snippet fails to read file

> Thanks for your help @jonathan-gibbons
> 
> Actually there's several ways to fix the issue:
> 
> 1. report the top-level exception (simplest, current PR)
> 2. report the direct cause if non-null, else report the top-level exception (most compatible with current code)
> 3. report the innermost exception for which `getCause()` is null (most helpful message for the user?)
> 
> Which of these do you prefer?

In general, exceptions are woefully underspecified, and unless you have specific reasons to know specific details of the exception being thrown, it is generally safest to just report the top-level exception.

-------------

PR: https://git.openjdk.org/jdk/pull/8826