Bug 468291 - Clarify Javadoc for @Optional
Change-Id: I39aa809d296750288313893d5a53f31013ae1107
Signed-off-by: Lars Vogel <Lars.Vogel@vogella.com>
diff --git a/bundles/org.eclipse.e4.core.di.annotations/src/org/eclipse/e4/core/di/annotations/Optional.java b/bundles/org.eclipse.e4.core.di.annotations/src/org/eclipse/e4/core/di/annotations/Optional.java
index 16468d0..dc3629a 100644
--- a/bundles/org.eclipse.e4.core.di.annotations/src/org/eclipse/e4/core/di/annotations/Optional.java
+++ b/bundles/org.eclipse.e4.core.di.annotations/src/org/eclipse/e4/core/di/annotations/Optional.java
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2009, 2013 IBM Corporation and others.
+ * Copyright (c) 2009, 2015 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
@@ -7,6 +7,7 @@
*
* Contributors:
* IBM Corporation - initial API and implementation
+ * Lars Vogel <Lars.Vogel@vogella.com> - Bug 468291
*******************************************************************************/
package org.eclipse.e4.core.di.annotations;
@@ -16,18 +17,27 @@
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
+
import javax.inject.Qualifier;
/**
* This annotation can be applied to methods, fields, and parameters to
* mark them as optional for the dependency injection. Typically, if the injector is
- * unable to find a value to inject, then injection will fail. However, if this annotation
- * is specified, then:
+ * unable to find a value to inject, then injection will fail. However if a value cannot be found
+ * and if this annotation is specified, then:
* <ul>
* <li> for parameters: a <code>null</code> value will be injected; </li>
* <li> for methods: the method calls will be skipped; </li>
* <li> for fields: the values will not be injected. </li>
* </ul>
+ *
+ * <p>
+ * Note that {@code null} is as an acceptable value and is not the same as a
+ * value not being found. For example, the {@code IEclipseContext}-based supplier distinguishes
+ * between a value being set to null (i.e., {@code context.set(SOMEKEY, null)})
+ * and the value not found (i.e., {@code context.remove(SOMEKEY)}).
+ * </p>
+ *
* <p>Example usage:
* <pre>
* public class Car {
