### Eclipse Workspace Patch 1.0
#P org.eclipse.jdt.core
Index: compiler/org/eclipse/jdt/internal/compiler/ast/JavadocSingleNameReference.java
===================================================================
RCS file: /cvsroot/eclipse/org.eclipse.jdt.core/compiler/org/eclipse/jdt/internal/compiler/ast/JavadocSingleNameReference.java,v
retrieving revision 1.10
diff -u -r1.10 JavadocSingleNameReference.java
--- compiler/org/eclipse/jdt/internal/compiler/ast/JavadocSingleNameReference.java	13 Oct 2006 19:20:45 -0000	1.10
+++ compiler/org/eclipse/jdt/internal/compiler/ast/JavadocSingleNameReference.java	12 Apr 2007 13:26:09 -0000
@@ -25,17 +25,20 @@
 	}
 
 	public void resolve(BlockScope scope) {
-		resolve(scope, true);
+		resolve(scope, true, !scope.compilerOptions().reportUnusedParameterWhenDocumented);
 	}
 
 	/**
 	 * Resolve without warnings
 	 */
-	public void resolve(BlockScope scope, boolean warn) {
+	public void resolve(BlockScope scope, boolean warn, boolean considerParamRefAsUsage) {
 		
 		LocalVariableBinding variableBinding = scope.findVariable(this.token);
 		if (variableBinding != null && variableBinding.isValidBinding() && ((variableBinding.tagBits & TagBits.IsArgument) != 0)) {
 			this.binding = variableBinding;
+			if (considerParamRefAsUsage) {
+				variableBinding.useFlag = LocalVariableBinding.USED;
+			}
 			return;
 		}
 		if (warn) {
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.54
diff -u -r1.54 Javadoc.java
--- compiler/org/eclipse/jdt/internal/compiler/ast/Javadoc.java	16 Mar 2007 18:28:59 -0000	1.54
+++ compiler/org/eclipse/jdt/internal/compiler/ast/Javadoc.java	12 Apr 2007 13:26:09 -0000
@@ -309,7 +309,8 @@
 		}
 
 		// @param tags
-		resolveParamTags(methScope, reportMissing);
+		boolean considerParamRefAsUsage = !methScope.compilerOptions().reportUnusedParameterWhenDocumented;
+		resolveParamTags(methScope, reportMissing, considerParamRefAsUsage);
 		resolveTypeParameterTags(methScope, reportMissing);
 
 		// @return tags
@@ -339,7 +340,7 @@
 		// Resolve param tags with invalid syntax
 		int length = this.invalidParameters == null ? 0 : this.invalidParameters.length;
 		for (int i = 0; i < length; i++) {
-			this.invalidParameters[i].resolve(methScope, false);
+			this.invalidParameters[i].resolve(methScope, false, false);
 		}
 	}
 	
@@ -445,26 +446,26 @@
 	/*
 	 * Resolve @param tags while method scope
 	 */
-	private void resolveParamTags(MethodScope methScope, boolean reportMissing) {
-		AbstractMethodDeclaration md = methScope.referenceMethod();
+	private void resolveParamTags(MethodScope scope, boolean reportMissing, boolean considerParamRefAsUsage) {
+		AbstractMethodDeclaration methodDecl = scope.referenceMethod();
 		int paramTagsSize = this.paramReferences == null ? 0 : this.paramReferences.length;
 
 		// If no referenced method (field initializer for example) then report a problem for each param tag
-		if (md == null) {
+		if (methodDecl == null) {
 			for (int i = 0; i < paramTagsSize; i++) {
 				JavadocSingleNameReference param = this.paramReferences[i];
-				methScope.problemReporter().javadocUnexpectedTag(param.tagSourceStart, param.tagSourceEnd);
+				scope.problemReporter().javadocUnexpectedTag(param.tagSourceStart, param.tagSourceEnd);
 			}
 			return;
 		}
 		
 		// If no param tags then report a problem for each method argument
-		int argumentsSize = md.arguments == null ? 0 : md.arguments.length;
+		int argumentsSize = methodDecl.arguments == null ? 0 : methodDecl.arguments.length;
 		if (paramTagsSize == 0) {
 			if (reportMissing) {
 				for (int i = 0; i < argumentsSize; i++) {
-					Argument arg = md.arguments[i];
-					methScope.problemReporter().javadocMissingParamTag(arg.name, arg.sourceStart, arg.sourceEnd, md.binding.modifiers);
+					Argument arg = methodDecl.arguments[i];
+					scope.problemReporter().javadocMissingParamTag(arg.name, arg.sourceStart, arg.sourceEnd, methodDecl.binding.modifiers);
 				}
 			}
 		} else {
@@ -474,13 +475,13 @@
 			// Scan all @param tags
 			for (int i = 0; i < paramTagsSize; i++) {
 				JavadocSingleNameReference param = this.paramReferences[i];
-				param.resolve(methScope);
+				param.resolve(scope, true, considerParamRefAsUsage);
 				if (param.binding != null && param.binding.isValidBinding()) {
 					// Verify duplicated tags
 					boolean found = false;
 					for (int j = 0; j < maxBindings && !found; j++) {
 						if (bindings[j] == param.binding) {
-							methScope.problemReporter().javadocDuplicatedParamTag(param.token, param.sourceStart, param.sourceEnd, md.binding.modifiers);
+							scope.problemReporter().javadocDuplicatedParamTag(param.token, param.sourceStart, param.sourceEnd, methodDecl.binding.modifiers);
 							found = true;
 						}
 					}
@@ -493,7 +494,7 @@
 			// Look for undocumented arguments
 			if (reportMissing) {
 				for (int i = 0; i < argumentsSize; i++) {
-					Argument arg = md.arguments[i];
+					Argument arg = methodDecl.arguments[i];
 					boolean found = false;
 					for (int j = 0; j < maxBindings && !found; j++) {
 						LocalVariableBinding binding = bindings[j];
@@ -502,7 +503,7 @@
 						}
 					}
 					if (!found) {
-						methScope.problemReporter().javadocMissingParamTag(arg.name, arg.sourceStart, arg.sourceEnd, md.binding.modifiers);
+						scope.problemReporter().javadocMissingParamTag(arg.name, arg.sourceStart, arg.sourceEnd, methodDecl.binding.modifiers);
 					}
 				}
 			}
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.571
diff -u -r1.571 JavaCore.java
--- model/org/eclipse/jdt/core/JavaCore.java	26 Mar 2007 17:03:13 -0000	1.571
+++ model/org/eclipse/jdt/core/JavaCore.java	12 Apr 2007 13:26:11 -0000
@@ -66,6 +66,8 @@
  *     IBM Corporation - added the following constants:
  *                                 COMPILER_PB_POTENTIAL_NULL_REFERENCE
  *                                 COMPILER_PB_REDUNDANT_NULL_CHECK
+ *     IBM Corporation - added the following constants:
+ *                                 COMPILER_PB_UNUSED_PARAMETER_WHEN_DOCUMENTED
  *******************************************************************************/
 package org.eclipse.jdt.core;
 
@@ -287,6 +289,12 @@
 	/**
 	 * Possible  configurable option ID.
 	 * @see #getDefaultOptions()
+	 * @since 3.3
+	 */
+	public static final String COMPILER_PB_UNUSED_PARAMETER_WHEN_DOCUMENTED = PLUGIN_ID + ".compiler.problem.unusedParameterWhenDocumented"; //$NON-NLS-1$
+	/**
+	 * Possible  configurable option ID.
+	 * @see #getDefaultOptions()
 	 * @since 2.0
 	 */
 	public static final String COMPILER_PB_UNUSED_IMPORT = PLUGIN_ID + ".compiler.problem.unusedImport"; //$NON-NLS-1$
@@ -1998,6 +2006,13 @@
 	 *     - possible values:   { "enabled", "disabled" }
 	 *     - default:           "disabled"
 	 *
+	 * COMPILER / Reporting Unused Parameter which is Documented by @param Clause
+	 *    When enabled, the compiler will still report unused parameters which are documented by @param clauses.
+	 *    The severity of the problem is controlled with option "org.eclipse.jdt.core.compiler.problem.unusedParameter".
+	 *     - option id:         "org.eclipse.jdt.core.compiler.problem.unusedParameterWhenDocumented"
+	 *     - possible values:   { "enabled", "disabled" }
+	 *     - default:           "disabled"
+	 *
 	 * COMPILER / Reporting Unused Import
 	 *    When enabled, the compiler will issue an error or a warning for unused import
 	 *    reference
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.180
diff -u -r1.180 CompilerOptions.java
--- compiler/org/eclipse/jdt/internal/compiler/impl/CompilerOptions.java	26 Feb 2007 08:49:00 -0000	1.180
+++ compiler/org/eclipse/jdt/internal/compiler/impl/CompilerOptions.java	12 Apr 2007 13:26:09 -0000
@@ -43,6 +43,7 @@
 	public static final String OPTION_ReportUnusedLocal = "org.eclipse.jdt.core.compiler.problem.unusedLocal"; //$NON-NLS-1$
 	public static final String OPTION_ReportUnusedParameter = "org.eclipse.jdt.core.compiler.problem.unusedParameter"; //$NON-NLS-1$
 	public static final String OPTION_ReportUnusedParameterWhenImplementingAbstract = "org.eclipse.jdt.core.compiler.problem.unusedParameterWhenImplementingAbstract"; //$NON-NLS-1$
+	public static final String OPTION_ReportUnusedParameterWhenDocumented = "org.eclipse.jdt.core.compiler.problem.unusedParameterWhenDocumented"; //$NON-NLS-1$
 	public static final String OPTION_ReportUnusedParameterWhenOverridingConcrete = "org.eclipse.jdt.core.compiler.problem.unusedParameterWhenOverridingConcrete"; //$NON-NLS-1$
 	public static final String OPTION_ReportUnusedImport = "org.eclipse.jdt.core.compiler.problem.unusedImport"; //$NON-NLS-1$
 	public static final String OPTION_ReportSyntheticAccessEmulation = "org.eclipse.jdt.core.compiler.problem.syntheticAccessEmulation"; //$NON-NLS-1$
@@ -270,6 +271,7 @@
 	// unused parameters report
 	public boolean reportUnusedParameterWhenImplementingAbstract = false;
 	public boolean reportUnusedParameterWhenOverridingConcrete = false;
+	public boolean reportUnusedParameterWhenDocumented = false;
 
 	// unused declaration of thrown exception
 	public boolean reportUnusedDeclaredThrownExceptionWhenOverriding = false;
@@ -418,6 +420,7 @@
 		optionsMap.put(OPTION_TaskCaseSensitive, this.isTaskCaseSensitive ? ENABLED : DISABLED);
 		optionsMap.put(OPTION_ReportUnusedParameterWhenImplementingAbstract, this.reportUnusedParameterWhenImplementingAbstract ? ENABLED : DISABLED);
 		optionsMap.put(OPTION_ReportUnusedParameterWhenOverridingConcrete, this.reportUnusedParameterWhenOverridingConcrete ? ENABLED : DISABLED);
+		optionsMap.put(OPTION_ReportUnusedParameterWhenDocumented, this.reportUnusedParameterWhenDocumented ? ENABLED : DISABLED);
 		optionsMap.put(OPTION_ReportSpecialParameterHidingField, this.reportSpecialParameterHidingField ? ENABLED : DISABLED);
 		optionsMap.put(OPTION_MaxProblemPerUnit, String.valueOf(this.maxProblemsPerUnit));
 		optionsMap.put(OPTION_InlineJsr, this.inlineJsrBytecode ? ENABLED : DISABLED);
@@ -697,6 +700,13 @@
 				this.reportUnusedParameterWhenOverridingConcrete = false;
 			}
 		}
+		if ((optionValue = optionsMap.get(OPTION_ReportUnusedParameterWhenDocumented)) != null) {
+			if (ENABLED.equals(optionValue)) {
+				this.reportUnusedParameterWhenDocumented = true;
+			} else if (DISABLED.equals(optionValue)) {
+				this.reportUnusedParameterWhenDocumented = false;
+			}
+		}		
 		if ((optionValue = optionsMap.get(OPTION_ReportSpecialParameterHidingField)) != null) {
 			if (ENABLED.equals(optionValue)) {
 				this.reportSpecialParameterHidingField = true;