### Eclipse Workspace Patch 1.0
#P org.eclipse.jdt.core
Index: compiler/org/eclipse/jdt/internal/compiler/ast/Javadoc.java
===================================================================
RCS file: /cvsroot/eclipse/org.eclipse.jdt.core/compiler/org/eclipse/jdt/internal/compiler/ast/Javadoc.java,v
retrieving revision 1.56
diff -u -r1.56 Javadoc.java
--- compiler/org/eclipse/jdt/internal/compiler/ast/Javadoc.java	25 Apr 2007 16:59:23 -0000	1.56
+++ compiler/org/eclipse/jdt/internal/compiler/ast/Javadoc.java	6 Sep 2007 12:48:53 -0000
@@ -13,6 +13,7 @@
 import org.eclipse.jdt.core.compiler.CharOperation;
 import org.eclipse.jdt.internal.compiler.ASTVisitor;
 import org.eclipse.jdt.internal.compiler.classfmt.ClassFileConstants;
+import org.eclipse.jdt.internal.compiler.impl.CompilerOptions;
 import org.eclipse.jdt.internal.compiler.lookup.*;
 import org.eclipse.jdt.internal.compiler.parser.JavadocTagConstants;
 
@@ -309,8 +310,8 @@
 		}
 
 		// @param tags
-		boolean considerParamRefAsUsage = methScope.compilerOptions().reportUnusedParameterIncludeDocCommentReference;
-		resolveParamTags(methScope, reportMissing, considerParamRefAsUsage);
+		CompilerOptions compilerOptions = methScope.compilerOptions();
+		resolveParamTags(methScope, reportMissing, compilerOptions.reportUnusedParameterIncludeDocCommentReference /* considerParamRefAsUsage*/);
 		resolveTypeParameterTags(methScope, reportMissing);
 
 		// @return tags
@@ -332,7 +333,7 @@
 		resolveThrowsTags(methScope, reportMissing);
 
 		// @value tag
-		boolean source15 = methScope.compilerOptions().sourceLevel >= ClassFileConstants.JDK1_5;
+		boolean source15 = compilerOptions.sourceLevel >= ClassFileConstants.JDK1_5;
 		if (!source15 && methDecl != null && this.valuePositions != -1) {
 			methScope.problemReporter().javadocUnexpectedTag((int)(this.valuePositions>>>32), (int) this.valuePositions);
 		}
Index: compiler/org/eclipse/jdt/internal/compiler/flow/ExceptionHandlingFlowContext.java
===================================================================
RCS file: /cvsroot/eclipse/org.eclipse.jdt.core/compiler/org/eclipse/jdt/internal/compiler/flow/ExceptionHandlingFlowContext.java,v
retrieving revision 1.38
diff -u -r1.38 ExceptionHandlingFlowContext.java
--- compiler/org/eclipse/jdt/internal/compiler/flow/ExceptionHandlingFlowContext.java	28 Mar 2006 20:32:37 -0000	1.38
+++ compiler/org/eclipse/jdt/internal/compiler/flow/ExceptionHandlingFlowContext.java	6 Sep 2007 12:48:53 -0000
@@ -81,11 +81,28 @@
 	}
 	    
 	// report errors for unreachable exception handlers
-	for (int i = 0, count = this.handledExceptions.length; i < count; i++) {
+	TypeBinding[] docCommentReferences = null;
+	int docCommentReferencesLength = 0;
+	if (scope.compilerOptions().
+				reportUnusedDeclaredThrownExceptionIncludeDocCommentReference &&
+			method.javadoc != null &&
+			method.javadoc.exceptionReferences != null &&
+			(docCommentReferencesLength = method.javadoc.exceptionReferences.length) > 0) {
+		docCommentReferences = new TypeBinding[docCommentReferencesLength];
+		for (int i = 0; i < docCommentReferencesLength; i++) {
+			docCommentReferences[i] = method.javadoc.exceptionReferences[i].resolvedType;
+		}
+	}
+	nextHandledException: for (int i = 0, count = this.handledExceptions.length; i < count; i++) {
 		int index = this.indexes.get(this.handledExceptions[i]);
 		int cacheIndex = index / ExceptionHandlingFlowContext.BitCacheSize;
 		int bitMask = 1 << (index % ExceptionHandlingFlowContext.BitCacheSize);
 		if ((this.isReached[cacheIndex] & bitMask) == 0) {
+			for (int j = 0; j < docCommentReferencesLength; j++) {
+				if (docCommentReferences[j] == this.handledExceptions[i]) {
+					continue nextHandledException;
+				}
+			}
 			scope.problemReporter().unusedDeclaredThrownException(
 				this.handledExceptions[index],
 				method,
Index: model/org/eclipse/jdt/core/JavaCore.java
===================================================================
RCS file: /cvsroot/eclipse/org.eclipse.jdt.core/model/org/eclipse/jdt/core/JavaCore.java,v
retrieving revision 1.580
diff -u -r1.580 JavaCore.java
--- model/org/eclipse/jdt/core/JavaCore.java	28 Aug 2007 10:03:38 -0000	1.580
+++ model/org/eclipse/jdt/core/JavaCore.java	6 Sep 2007 12:48:54 -0000
@@ -68,6 +68,8 @@
  *                                 COMPILER_PB_REDUNDANT_NULL_CHECK
  *     IBM Corporation - added the following constants:
  *                                 COMPILER_PB_UNUSED_PARAMETER_INCLUDE_DOC_COMMENT_REFERENCE
+ *     IBM Corporation - added the following constants:
+ *                                 COMPILER_PB_UNUSED_DECLARED_THROWN_EXCEPTION_INCLUDE_DOC_COMMENT_REFERENCE
  *******************************************************************************/
 package org.eclipse.jdt.core;
 
@@ -438,6 +440,12 @@
 	/**
 	 * Possible  configurable option ID.
 	 * @see #getDefaultOptions()
+	 * @since 3.4
+	 */
+	public static final String COMPILER_PB_UNUSED_DECLARED_THROWN_EXCEPTION_INCLUDE_DOC_COMMENT_REFERENCE = PLUGIN_ID + ".compiler.problem.unusedDeclaredThrownExceptionIncludeDocCommentReference"; //$NON-NLS-1$
+	/**
+	 * Possible  configurable option ID.
+	 * @see #getDefaultOptions()
 	 * @since 3.0
 	 */
 	public static final String COMPILER_PB_UNQUALIFIED_FIELD_ACCESS = PLUGIN_ID + ".compiler.problem.unqualifiedFieldAccess"; //$NON-NLS-1$
@@ -2213,7 +2221,7 @@
 	 *     - possible values:   { "error", "warning", "ignore" }
 	 *     - default:           "ignore"
 	 *
-	 * COMPILER / Reporting Unused Declared Thrown Exception in Overridind Method
+	 * COMPILER / Reporting Unused Declared Thrown Exception in Overriding Method
 	 *    When disabled, the compiler will not include overriding methods in its diagnosis for unused declared
 	 *    thrown exceptions.
 	 *    <br>
@@ -2222,6 +2230,16 @@
 	 *     - possible values:   { "enabled", "disabled" }
 	 *     - default:           "disabled"
 	 *
+	 * COMPILER / Consider Reference in Doc Comment for Unused Declared Thrown Exception Check
+	 *    When enabled, the compiler will consider doc comment references to exceptions (i.e. @throws clauses) for the unused
+	 *    declared thrown exception check. Thus, documented exceptions will be considered as mandated as per doc contract.
+	 *    The severity of the unused declared thrown exception problem is controlled with option "org.eclipse.jdt.core.compiler.problem.unusedDeclaredThrownException".
+	 *    Note: this option has no effect until the doc comment support is enabled according to the 
+	 *    option "org.eclipse.jdt.core.compiler.doc.comment.support".
+	 *     - option id:         "org.eclipse.jdt.core.compiler.problem.unusedDeclaredThrownExceptionIncludeDocReference"
+	 *     - possible values:   { "enabled", "disabled" }
+	 *     - default:           "enabled"
+	 *
 	 * COMPILER / Reporting Unqualified Access to Field
 	 *    When enabled, the compiler will issue an error or a warning when a field is access without any qualification.
 	 *    In order to improve code readability, it should be qualified, e.g. 'x' should rather be written 'this.x'.
Index: compiler/org/eclipse/jdt/internal/compiler/impl/CompilerOptions.java
===================================================================
RCS file: /cvsroot/eclipse/org.eclipse.jdt.core/compiler/org/eclipse/jdt/internal/compiler/impl/CompilerOptions.java,v
retrieving revision 1.184
diff -u -r1.184 CompilerOptions.java
--- compiler/org/eclipse/jdt/internal/compiler/impl/CompilerOptions.java	7 May 2007 17:01:22 -0000	1.184
+++ compiler/org/eclipse/jdt/internal/compiler/impl/CompilerOptions.java	6 Sep 2007 12:48:53 -0000
@@ -79,6 +79,7 @@
 	public static final String OPTION_ReportFinallyBlockNotCompletingNormally = "org.eclipse.jdt.core.compiler.problem.finallyBlockNotCompletingNormally"; //$NON-NLS-1$
 	public static final String OPTION_ReportUnusedDeclaredThrownException = "org.eclipse.jdt.core.compiler.problem.unusedDeclaredThrownException"; //$NON-NLS-1$
 	public static final String OPTION_ReportUnusedDeclaredThrownExceptionWhenOverriding = "org.eclipse.jdt.core.compiler.problem.unusedDeclaredThrownExceptionWhenOverriding"; //$NON-NLS-1$
+	public static final String OPTION_ReportUnusedDeclaredThrownExceptionIncludeDocCommentReference = "org.eclipse.jdt.core.compiler.problem.unusedDeclaredThrownExceptionIncludeDocCommentReference"; //$NON-NLS-1$
 	public static final String OPTION_ReportUnqualifiedFieldAccess = "org.eclipse.jdt.core.compiler.problem.unqualifiedFieldAccess"; //$NON-NLS-1$
 	public static final String OPTION_ReportUncheckedTypeOperation = "org.eclipse.jdt.core.compiler.problem.uncheckedTypeOperation"; //$NON-NLS-1$
 	public static final String OPTION_ReportRawTypeReference =  "org.eclipse.jdt.core.compiler.problem.rawTypeReference"; //$NON-NLS-1$
@@ -275,6 +276,7 @@
 
 	// unused declaration of thrown exception
 	public boolean reportUnusedDeclaredThrownExceptionWhenOverriding = false;
+	public boolean reportUnusedDeclaredThrownExceptionIncludeDocCommentReference = true;
 
 	// constructor/setter parameter hiding
 	public boolean reportSpecialParameterHidingField = false;
@@ -396,6 +398,7 @@
 		optionsMap.put(OPTION_ReportFinallyBlockNotCompletingNormally, getSeverityString(FinallyBlockNotCompleting));
 		optionsMap.put(OPTION_ReportUnusedDeclaredThrownException, getSeverityString(UnusedDeclaredThrownException));
 		optionsMap.put(OPTION_ReportUnusedDeclaredThrownExceptionWhenOverriding, this.reportUnusedDeclaredThrownExceptionWhenOverriding ? ENABLED : DISABLED);
+		optionsMap.put(OPTION_ReportUnusedDeclaredThrownExceptionIncludeDocCommentReference, this.reportUnusedDeclaredThrownExceptionIncludeDocCommentReference ? ENABLED : DISABLED);
 		optionsMap.put(OPTION_ReportUnqualifiedFieldAccess, getSeverityString(UnqualifiedFieldAccess));
 		optionsMap.put(OPTION_ReportUncheckedTypeOperation, getSeverityString(UncheckedTypeOperation));
 		optionsMap.put(OPTION_ReportRawTypeReference, getSeverityString(RawTypeReference));
@@ -659,6 +662,13 @@
 				this.reportUnusedDeclaredThrownExceptionWhenOverriding = false;
 			}
 		}
+		if ((optionValue = optionsMap.get(OPTION_ReportUnusedDeclaredThrownExceptionIncludeDocCommentReference)) != null) {
+			if (ENABLED.equals(optionValue)) {
+				this.reportUnusedDeclaredThrownExceptionIncludeDocCommentReference = true;
+			} else if (DISABLED.equals(optionValue)) {
+				this.reportUnusedDeclaredThrownExceptionIncludeDocCommentReference = false;
+			}
+		}
 		if ((optionValue = optionsMap.get(OPTION_Compliance)) != null) {
 			long level = versionToJdkLevel(optionValue);
 			if (level != 0) this.complianceLevel = level;
@@ -969,8 +979,9 @@
 		buf.append("\n\t\t+ visibility level to report missing javadoc comments: ").append(getVisibilityString(this.reportMissingJavadocCommentsVisibility)); //$NON-NLS-1$
 		buf.append("\n\t\t+ report missing javadoc comments in overriding methods: ").append(this.reportMissingJavadocCommentsOverriding ? ENABLED : DISABLED); //$NON-NLS-1$
 		buf.append("\n\t- finally block not completing normally: ").append(getSeverityString(FinallyBlockNotCompleting)); //$NON-NLS-1$
-		buf.append("\n\t- unused declared thrown exception: ").append(getSeverityString(UnusedDeclaredThrownException)); //$NON-NLS-1$
-		buf.append("\n\t- unused declared thrown exception when overriding: ").append(this.reportUnusedDeclaredThrownExceptionWhenOverriding ? ENABLED : DISABLED); //$NON-NLS-1$
+		buf.append("\n\t- report unused declared thrown exception: ").append(getSeverityString(UnusedDeclaredThrownException)); //$NON-NLS-1$
+		buf.append("\n\t- report unused declared thrown exception when overriding: ").append(this.reportUnusedDeclaredThrownExceptionWhenOverriding ? ENABLED : DISABLED); //$NON-NLS-1$
+		buf.append("\n\t- report unused declared thrown exception include doc comment reference: ").append(this.reportUnusedDeclaredThrownExceptionIncludeDocCommentReference ? ENABLED : DISABLED); //$NON-NLS-1$
 		buf.append("\n\t- unnecessary else: ").append(getSeverityString(UnnecessaryElse)); //$NON-NLS-1$
 		buf.append("\n\t- JDK compliance level: "+ versionFromJdkLevel(this.complianceLevel)); //$NON-NLS-1$
 		buf.append("\n\t- JDK source level: "+ versionFromJdkLevel(this.sourceLevel)); //$NON-NLS-1$
#P org.eclipse.jdt.core.tests.compiler
Index: src/org/eclipse/jdt/core/tests/compiler/regression/ProgrammingProblemsTest.java
===================================================================
RCS file: /cvsroot/eclipse/org.eclipse.jdt.core.tests.compiler/src/org/eclipse/jdt/core/tests/compiler/regression/ProgrammingProblemsTest.java,v
retrieving revision 1.1
diff -u -r1.1 ProgrammingProblemsTest.java
--- src/org/eclipse/jdt/core/tests/compiler/regression/ProgrammingProblemsTest.java	5 Sep 2007 13:36:49 -0000	1.1
+++ src/org/eclipse/jdt/core/tests/compiler/regression/ProgrammingProblemsTest.java	6 Sep 2007 12:48:58 -0000
@@ -349,7 +349,7 @@
 // exceptions using the Javadoc
 // https://bugs.eclipse.org/bugs/show_bug.cgi?id=73244
 // @throws disables by default
-public void _test0009_declared_thrown_checked_exceptions() {
+public void test0009_declared_thrown_checked_exceptions() {
 	Map customOptions = new HashMap();
 	customOptions.put(CompilerOptions.OPTION_DocCommentSupport, 
 			CompilerOptions.ENABLED);
@@ -384,12 +384,12 @@
 // exceptions using the Javadoc
 // https://bugs.eclipse.org/bugs/show_bug.cgi?id=73244
 // @throws disabling can be disabled
-public void _test0010_declared_thrown_checked_exceptions() {
+public void test0010_declared_thrown_checked_exceptions() {
 	Map customOptions = new HashMap();
 	customOptions.put(CompilerOptions.OPTION_DocCommentSupport, 
 			CompilerOptions.ENABLED);
-/*	customOptions.put(CompilerOptions.OPTION_ReportUnusedDeclaredThrownExceptionIncludeDocCommentReference, 
-			CompilerOptions.DISABLED); */
+	customOptions.put(CompilerOptions.OPTION_ReportUnusedDeclaredThrownExceptionIncludeDocCommentReference, 
+			CompilerOptions.DISABLED);
 	runTest(
 		new String[] {
 			"X.java",
@@ -406,7 +406,12 @@
 			} /* warningOptions */,
 		null /* ignoreOptions */,
 		false /* expectingCompilerErrors */,
-		"ERR" /* expectedCompilerLog */,
+		"----------\n" + 
+		"1. WARNING in X.java (at line 4)\n" + 
+		"	public void foo() throws IOException {\n" + 
+		"	                         ^^^^^^^^^^^\n" + 
+		"The declared exception IOException is not actually thrown by the method foo() from type X\n" + 
+		"----------\n" /* expectedCompilerLog */,
 		"" /* expectedOutputString */,
 		false /* forceExecution */,
 		null /* classLib */,
@@ -481,4 +486,45 @@
 		null /* clientRequestor */,
 		true /* skipJavac */);
 }
+
+// disabling the reporting of unnecessary declaration of thrown checked 
+// exceptions using the Javadoc
+// https://bugs.eclipse.org/bugs/show_bug.cgi?id=73244
+// @throws disables by default, but only exact matches work
+public void test0013_declared_thrown_checked_exceptions() {
+	Map customOptions = new HashMap();
+	customOptions.put(CompilerOptions.OPTION_DocCommentSupport, 
+			CompilerOptions.ENABLED);
+	runTest(
+		new String[] {
+			"X.java",
+			"import java.io.IOException;\n" + 
+			"import java.io.EOFException;\n" + 
+			"public class X {\n" + 
+			"/** @throws EOFException does not mute warning for IOException **/\n" + 
+			"  public void foo() throws IOException {\n" + 
+			"  }\n" + 
+			"}\n"
+			},
+		null /* errorOptions */,
+		new String[] {
+			CompilerOptions.OPTION_ReportUnusedDeclaredThrownException
+			} /* warningOptions */,
+		null /* ignoreOptions */,
+		false /* expectingCompilerErrors */,
+		"----------\n" + 
+		"1. WARNING in X.java (at line 5)\n" + 
+		"	public void foo() throws IOException {\n" + 
+		"	                         ^^^^^^^^^^^\n" + 
+		"The declared exception IOException is not actually thrown by the method foo() from type X\n" + 
+		"----------\n" /* expectedCompilerLog */,
+		"" /* expectedOutputString */,
+		false /* forceExecution */,
+		null /* classLib */,
+		true /* shouldFlushOutputDirectory */, 
+		null /* vmArguments */, 
+		customOptions,
+		null /* clientRequestor */,
+		true /* skipJavac */);
+}
 }
\ No newline at end of file
Index: src/org/eclipse/jdt/core/tests/compiler/regression/BatchCompilerTest.java
===================================================================
RCS file: /cvsroot/eclipse/org.eclipse.jdt.core.tests.compiler/src/org/eclipse/jdt/core/tests/compiler/regression/BatchCompilerTest.java,v
retrieving revision 1.117
diff -u -r1.117 BatchCompilerTest.java
--- src/org/eclipse/jdt/core/tests/compiler/regression/BatchCompilerTest.java	5 Sep 2007 13:36:49 -0000	1.117
+++ src/org/eclipse/jdt/core/tests/compiler/regression/BatchCompilerTest.java	6 Sep 2007 12:48:58 -0000
@@ -1277,6 +1277,7 @@
 			"		<option key=\"org.eclipse.jdt.core.compiler.problem.unnecessaryTypeCheck\" value=\"ignore\"/>\n" +
 			"		<option key=\"org.eclipse.jdt.core.compiler.problem.unqualifiedFieldAccess\" value=\"ignore\"/>\n" +
 			"		<option key=\"org.eclipse.jdt.core.compiler.problem.unusedDeclaredThrownException\" value=\"ignore\"/>\n" +
+			"		<option key=\"org.eclipse.jdt.core.compiler.problem.unusedDeclaredThrownExceptionIncludeDocCommentReference\" value=\"enabled\"/>\n" +
 			"		<option key=\"org.eclipse.jdt.core.compiler.problem.unusedDeclaredThrownExceptionWhenOverriding\" value=\"disabled\"/>\n" +
 			"		<option key=\"org.eclipse.jdt.core.compiler.problem.unusedImport\" value=\"warning\"/>\n" +
 			"		<option key=\"org.eclipse.jdt.core.compiler.problem.unusedLabel\" value=\"warning\"/>\n" +