Bug 217995 - Documentation for JavaCore#COMPILER_PB_UNUSED_DECLARED_THROWN_EXCEPTION and JavaCore#COMPILER_PB_UNUSED_DECLARED_THROWN_EXCEPTION_INCLUDE_UNCHECKED_EXCEPTIONS fails to make crystal-clear the cases of Exception and Throwable
Summary: Documentation for JavaCore#COMPILER_PB_UNUSED_DECLARED_THROWN_EXCEPTION and J...
Status: VERIFIED FIXED
Alias: None
Product: JDT
Classification: Eclipse Project
Component: Core (show other bugs)
Version: 3.4   Edit
Hardware: PC All
: P3 normal (vote)
Target Milestone: 3.4 M6   Edit
Assignee: Maxime Daniel CLA
QA Contact:
URL:
Whiteboard:
Keywords:
Depends on:
Blocks:
 
Reported: 2008-02-06 08:47 EST by Maxime Daniel CLA
Modified: 2008-03-25 13:09 EDT (History)
1 user (show)

See Also:

Attachments
Fix (2.21 KB, patch)
2008-02-08 04:25 EST, Maxime Daniel CLA 		no flags Details | Diff
View All Add an attachment (proposed patch, testcase, etc.)

Note You need to log in before you can comment on or make changes to this bug.
Description Maxime Daniel CLA 2008-02-06 08:47:29 EST 
Source based, v_835.

While checking the N&N for 3.4 M5, Jérôme pointed out that Throwable and Exception are not unchecked exceptions, which spun the following discussion:
'Indeed, JLS 3 section that defines this is 11, which stipulates that exceptions are instances of Throwable and inheriting classes, and section 11.2 that stipulates that unchecked exceptions are exactly instances of RuntimeException, Error, and their subclasses. 

As far as the warning behavior is concerned (not the compiler behavior re. catching exceptions at the calling point), Throwable, while being a checked exception, behaves as if it was unchecked, because unchecked exceptions are Throwable-s. The same must be true of Exception. These are not cited at all in the doc for corresponding JavaCore options. COMPILER_PB_UNUSED_DECLARED_THROWN_EXCEPTION fails to point the Throwable and Exception checked exceptions that it does not considers (unless COMPILER_PB_UNUSED_DECLARED_THROWN_EXCEPTION_INCLUDE_UNCHECKED_EXCEPTIONS is positioned).'

Need to improve the doc for both constants.
Comment 1 Maxime Daniel CLA 2008-02-08 04:25:51 EST 
Created attachment 89232 [details]
Fix

When looking closer at the issue, it occurred to me that the comment for COMPILER_PB_UNUSED_DECLARED_THROWN_EXCEPTION was unduly privileging COMPILER_PB_UNUSED_DECLARED_THROWN_EXCEPTION_INCLUDE_UNCHECKED_EXCEPTIONS over other tuning constants, hence I went for some symmetry. The fact that we use @link and that it is well leveraged both in the IDE and the generated javadoc helps.

I did not expand the rationale for treating Throwable and Exception differently from other checked exceptions, because I felt this would make the doc significantly heavier. For the interested reader, the reason is that these are the only two checked exceptions that can be (and are, by the way) extended by unchecked exceptions. Consequently, a throws of these can be 'reached' by unchecked exceptions that need not be explicitly thrown in the method body, exactly like declared thrown unchecked exceptions can be reached without the code showing it much prominently. Since they behaved like unchecked exceptions in this respect, we decided to treat them as unchecked exceptions (solely wrt this diagnostic, of course).

This is a doc only, straightforward change, so I will release it next week. Kent, please yell if you disagree.
Comment 2 Maxime Daniel CLA 2008-02-18 03:58:59 EST 
Released for 3.4M6.
Comment 3 Kent Johnson CLA 2008-03-25 13:09:27 EDT 
Verified for 3.4M6 using build I20080324-1300