Clarify some documentation about linked bindings and child injectors.

3 files changed, 12 insertions, 8 deletions

diff --git a/core/src/com/google/inject/Binder.java b/core/src/com/google/inject/Binder.java
index dae38125..91f436f6 100644
--- a/core/src/com/google/inject/Binder.java
+++ b/core/src/com/google/inject/Binder.java
@@ -429,8 +429,8 @@ public interface Binder {
   /**
    * Instructs the Injector that bindings must be listed in a Module in order to
    * be injected. Classes that are not explicitly bound in a module cannot be
-   * injected. Bindings created through a linked binding (
-   * <code>bind(Foo.class).to(FooImpl.class)</code>) are allowed, but the
+   * injected. Bindings created through a linked binding
+   * (<code>bind(Foo.class).to(FooImpl.class)</code>) are allowed, but the
    * implicit binding (<code>FooImpl</code>) cannot be directly injected unless
    * it is also explicitly bound (<code>bind(FooImpl.class)</code>).
    * <p>
@@ -447,10 +447,11 @@ public interface Binder {
    * does, the behavior is limited only to that child or any grandchildren. No
    * siblings of the child will require explicit bindings.
    * <p>
-   * If the parent did not require explicit bindings but the child does, it is
-   * possible that a linked binding in the child may add a JIT binding to the
-   * parent. The child will not be allowed to reference the target binding
-   * directly, but the parent and other children of the parent may be able to.
+   * In the absence of an explicit binding for the target, linked bindings in
+   * child injectors create a binding for the target in the parent. Since this
+   * behavior can be surprising, it causes an error instead if explicit bindings
+   * are required. To avoid this error, add an explicit binding for the target,
+   * either in the child or the parent.
    * 
    * @since 3.0
    */
diff --git a/core/src/com/google/inject/internal/Errors.java b/core/src/com/google/inject/internal/Errors.java
index 65f7e0b5..385d4b82 100644
--- a/core/src/com/google/inject/internal/Errors.java
+++ b/core/src/com/google/inject/internal/Errors.java
@@ -141,7 +141,10 @@ public final class Errors implements Serializable {
   }
 
   public Errors jitDisabledInParent(Key<?> key) {
-    return addMessage("Explicit bindings are required and %s would be bound in a parent injector.", key);
+    return addMessage(
+        "Explicit bindings are required and %s would be bound in a parent injector.%n"
+        + "Please add an explicit binding for it, either in the child or the parent.",
+        key);
   }
 
   public Errors atInjectRequired(Class clazz) {
diff --git a/core/src/com/google/inject/internal/InjectorImpl.java b/core/src/com/google/inject/internal/InjectorImpl.java
index e20035ac..be1c4c8b 100644
--- a/core/src/com/google/inject/internal/InjectorImpl.java
+++ b/core/src/com/google/inject/internal/InjectorImpl.java
@@ -101,7 +101,7 @@ final class InjectorImpl implements Injector, Lookups {
     NO_JIT,
     /** allows existing just in time bindings, but does not allow new ones */
     EXISTING_JIT,
-    /** allows existing just in time bindings & allows new ones to be created in the current injector */
+    /** allows existing just in time bindings & allows new ones to be created */
     NEW_OR_EXISTING_JIT,
   }