new javadoc for @Inject
git-svn-id: https://google-guice.googlecode.com/svn/trunk@191 d779f126-a31b-0410-b53b-1d3aecad763e
diff --git a/src/com/google/inject/Inject.java b/src/com/google/inject/Inject.java
index 4c88381..ea11dd4 100644
--- a/src/com/google/inject/Inject.java
+++ b/src/com/google/inject/Inject.java
@@ -24,7 +24,27 @@
import java.lang.annotation.Target;
/**
- * <p>Annotates members which should have their value[s] injected.
+ * Annotates the members of your implementation class (constructors, methods
+ * and fields) into which the container should inject appropriate references or
+ * values. The Container fulfills injection requests for:
+ *
+ * <ul>
+ * <li>every instance it constructs, whether this construction is in response to
+ * {@link Container#getInstance}, {@link Locator#get} on an injected Locator,
+ * or to fulfill another {@code @Inject} request (recursive). The class being
+ * constructed must have exactly one of its constructors marked with
+ * {@code @Inject}, or must have a constructor taking no parameters. The
+ * container then proceeds to perform method and field injections.
+ *
+ * <li>pre-constructed instances passed to {@link Container#injectMembers}.
+ * In this case any injectable constructor is, of course, ignored.
+ *
+ * <li>static fields and methods of classes which any Module has specifically
+ * requested static injection for, using {@link Binder#requestStaticInjection}.
+ * </ul>
+ *
+ * In all cases, a member can be injected regardless of its Java access
+ * specifier (private, default, protected, public).
*
* @author crazybob@google.com (Bob Lee)
*/
@@ -33,11 +53,13 @@
public @interface Inject {
/**
- * Indicates whether injection at the target is optional or not. The default
- * is {@code false}. Can be used on methods and fields. If a method has
- * multiple parameters and one parameter binding is missing, the method
- * won't be invoked at all. Not applicable to constructors or other
- * annotations.
+ * If true, and the appropriate binding is not present in the container,
+ * the container will skip injection of this method or field rather than
+ * produce an error. When applied to a field, any default value already
+ * assigned to the field will remain (guice will not actively null out the
+ * field). When applied to a method, the method will only be invoked if
+ * bindings for <i>all</i> parameters are found. When applied to a
+ * constructor, an error will result upon container creation.
*/
boolean optional() default false;
}
