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;
 }