Merge pull request #920 from google/merge-internal-changes

Merge internal changes.

26 files changed, 48 insertions, 30 deletions

diff --git a/core/src/com/google/inject/internal/package-info.java b/core/src/com/google/inject/internal/package-info.java
index 657d25a4..4116f110 100644
--- a/core/src/com/google/inject/internal/package-info.java
+++ b/core/src/com/google/inject/internal/package-info.java
@@ -17,5 +17,4 @@
 /**
  * <i>Guice</i> (sounds like like "juice")
  */
-
-package com.google.inject.internal;
\ No newline at end of file
+package com.google.inject.internal;
diff --git a/core/src/com/google/inject/spi/ElementVisitor.java b/core/src/com/google/inject/spi/ElementVisitor.java
index f0d9d138..bc0d9106 100644
--- a/core/src/com/google/inject/spi/ElementVisitor.java
+++ b/core/src/com/google/inject/spi/ElementVisitor.java
@@ -91,6 +91,8 @@ public interface ElementVisitor<V> {
   
   /**
    * Visit a provision listener binding.
+   *
+   * @since 4.0
    */
   V visit(ProvisionListenerBinding binding);
   
diff --git a/core/src/com/google/inject/spi/ProviderLookup.java b/core/src/com/google/inject/spi/ProviderLookup.java
index a2324315..3cc2d050 100644
--- a/core/src/com/google/inject/spi/ProviderLookup.java
+++ b/core/src/com/google/inject/spi/ProviderLookup.java
@@ -60,6 +60,7 @@ public final class ProviderLookup<T> implements Element {
     return dependency.getKey();
   }
 
+  /** @since 4.0 */
   public Dependency<T> getDependency() {
     return dependency;
   }
diff --git a/core/src/com/google/inject/spi/package-info.java b/core/src/com/google/inject/spi/package-info.java
index bbf05280..12248376 100644
--- a/core/src/com/google/inject/spi/package-info.java
+++ b/core/src/com/google/inject/spi/package-info.java
@@ -17,5 +17,4 @@
 /**
  * Guice service provider interface
  */
-
-package com.google.inject.spi;
\ No newline at end of file
+package com.google.inject.spi;
diff --git a/extensions/assistedinject/src/com/google/inject/assistedinject/package-info.java b/extensions/assistedinject/src/com/google/inject/assistedinject/package-info.java
index b0579099..9fc5b3e2 100644
--- a/extensions/assistedinject/src/com/google/inject/assistedinject/package-info.java
+++ b/extensions/assistedinject/src/com/google/inject/assistedinject/package-info.java
@@ -16,6 +16,6 @@
 
 /**
  * Extension for combining factory interfaces with injection; this extension requires {@code
- * guice-assistedinject-3.0.jar}.
+ * guice-assistedinject.jar}.
  */
-package com.google.inject.assistedinject;
\ No newline at end of file
+package com.google.inject.assistedinject;
diff --git a/extensions/grapher/src/com/google/inject/grapher/BindingEdge.java b/extensions/grapher/src/com/google/inject/grapher/BindingEdge.java
index 9984f19c..92d72ba1 100644
--- a/extensions/grapher/src/com/google/inject/grapher/BindingEdge.java
+++ b/extensions/grapher/src/com/google/inject/grapher/BindingEdge.java
@@ -22,6 +22,7 @@ import com.google.common.base.Objects;
  * Edge that connects an interface to the type or instance that is bound to implement it.
  *
  * @author phopkins@gmail.com (Pete Hopkins)
+ * @since 4.0 (since 2.0 as an interface)
  */
 public class BindingEdge extends Edge {
   /**
diff --git a/extensions/grapher/src/com/google/inject/grapher/DependencyEdge.java b/extensions/grapher/src/com/google/inject/grapher/DependencyEdge.java
index 94f63169..a8fe7bbc 100644
--- a/extensions/grapher/src/com/google/inject/grapher/DependencyEdge.java
+++ b/extensions/grapher/src/com/google/inject/grapher/DependencyEdge.java
@@ -24,6 +24,7 @@ import com.google.inject.spi.InjectionPoint;
  * dependency.
  *
  * @author phopkins@gmail.com (Pete Hopkins)
+ * @since 4.0 (since 2.0 as an interface)
  */
 public class DependencyEdge extends Edge {
   /**
diff --git a/extensions/grapher/src/com/google/inject/grapher/ImplementationNode.java b/extensions/grapher/src/com/google/inject/grapher/ImplementationNode.java
index f85fc96f..424ee1a6 100644
--- a/extensions/grapher/src/com/google/inject/grapher/ImplementationNode.java
+++ b/extensions/grapher/src/com/google/inject/grapher/ImplementationNode.java
@@ -26,8 +26,8 @@ import java.util.Collection;
  * {@link Member}s that are {@link com.google.inject.spi.InjectionPoint}s.
  *
  * @see DependencyEdge
- *
  * @author phopkins@gmail.com (Pete Hopkins)
+ * @since 4.0 (since 2.0 as an interface)
  */
 public class ImplementationNode extends Node {
   private final Collection<Member> members;
diff --git a/extensions/grapher/src/com/google/inject/grapher/InjectorGrapher.java b/extensions/grapher/src/com/google/inject/grapher/InjectorGrapher.java
index 37bd6e13..2d9efcdf 100644
--- a/extensions/grapher/src/com/google/inject/grapher/InjectorGrapher.java
+++ b/extensions/grapher/src/com/google/inject/grapher/InjectorGrapher.java
@@ -27,19 +27,18 @@ import java.util.Set;
  * whole dependency graph or just transitive dependencies of a given set of nodes.
  *
  * @author phopkins@gmail.com (Pete Hopkins)
+ * @since 4.0 (since 2.0 as a concrete class with a different API)
  */
 public interface InjectorGrapher {
 
   /**
    * Graphs the guice dependency graph for the given injector using default starting keys.
-   * @since 4.0
    */
   void graph(Injector injector) throws IOException;
 
   /**
    * Graphs the guice dependency graph for the given injector using the given starting keys and
    * their transitive dependencies.
-   * @since 4.0
    */
   void graph(Injector injector, Set<Key<?>> root) throws IOException;
 }
diff --git a/extensions/grapher/src/com/google/inject/grapher/InterfaceNode.java b/extensions/grapher/src/com/google/inject/grapher/InterfaceNode.java
index 58ae2f03..c23008d6 100644
--- a/extensions/grapher/src/com/google/inject/grapher/InterfaceNode.java
+++ b/extensions/grapher/src/com/google/inject/grapher/InterfaceNode.java
@@ -20,8 +20,8 @@ package com.google.inject.grapher;
  * Node for an interface type that has been bound to an implementation class or instance.
  *
  * @see BindingEdge
- *
  * @author phopkins@gmail.com (Pete Hopkins)
+ * @since 4.0 (since 2.0 as an interface)
  */
 public class InterfaceNode extends Node {
   public InterfaceNode(NodeId id, Object source) {
diff --git a/extensions/grapher/src/com/google/inject/grapher/NodeId.java b/extensions/grapher/src/com/google/inject/grapher/NodeId.java
index d29d3f59..33df33d1 100644
--- a/extensions/grapher/src/com/google/inject/grapher/NodeId.java
+++ b/extensions/grapher/src/com/google/inject/grapher/NodeId.java
@@ -33,6 +33,7 @@ public final class NodeId {
 
   /**
    * Type of node.
+   *
    * @since 4.0
    */
   public enum NodeType {
diff --git a/extensions/grapher/src/com/google/inject/grapher/TransitiveDependencyVisitor.java b/extensions/grapher/src/com/google/inject/grapher/TransitiveDependencyVisitor.java
index b72e8765..c2da39f1 100644
--- a/extensions/grapher/src/com/google/inject/grapher/TransitiveDependencyVisitor.java
+++ b/extensions/grapher/src/com/google/inject/grapher/TransitiveDependencyVisitor.java
@@ -43,7 +43,7 @@ import java.util.Set;
  * @author phopkins@gmail.com (Pete Hopkins)
  */
 public class TransitiveDependencyVisitor
-extends DefaultBindingTargetVisitor<Object, Collection<Key<?>>> {
+    extends DefaultBindingTargetVisitor<Object, Collection<Key<?>>> {
 
   private Collection<Key<?>> visitHasDependencies(HasDependencies hasDependencies) {
     Set<Key<?>> dependencies = Sets.newHashSet();
@@ -83,6 +83,7 @@ extends DefaultBindingTargetVisitor<Object, Collection<Key<?>>> {
     return ImmutableSet.<Key<?>>of(binding.getProviderKey());
   }
 
+  /** @since 4.0 */
   @Override public Collection<Key<?>> visitOther(Binding<?> binding) {
     return ImmutableSet.of();
   }
diff --git a/extensions/grapher/src/com/google/inject/grapher/graphviz/GraphvizEdge.java b/extensions/grapher/src/com/google/inject/grapher/graphviz/GraphvizEdge.java
index 39fd4bd8..0a8ff982 100644
--- a/extensions/grapher/src/com/google/inject/grapher/graphviz/GraphvizEdge.java
+++ b/extensions/grapher/src/com/google/inject/grapher/graphviz/GraphvizEdge.java
@@ -45,6 +45,7 @@ public class GraphvizEdge {
     this.headNodeId = headNodeId;
   }
 
+  /** @since 4.0 */
   public NodeId getHeadNodeId() {
     return headNodeId;
   }
@@ -73,6 +74,7 @@ public class GraphvizEdge {
     this.arrowHead = ImmutableList.copyOf(arrowHead);
   }
 
+  /** @since 4.0 */
   public NodeId getTailNodeId() {
     return tailNodeId;
   }
diff --git a/extensions/grapher/src/com/google/inject/grapher/graphviz/GraphvizNode.java b/extensions/grapher/src/com/google/inject/grapher/graphviz/GraphvizNode.java
index ed94c177..37a1f793 100644
--- a/extensions/grapher/src/com/google/inject/grapher/graphviz/GraphvizNode.java
+++ b/extensions/grapher/src/com/google/inject/grapher/graphviz/GraphvizNode.java
@@ -47,10 +47,12 @@ public class GraphvizNode {
   /** {@link Map} from port ID to field title */
   private Map<String, String> fields = Maps.newLinkedHashMap();
 
+  /** @since 4.0 */
   public GraphvizNode(NodeId nodeId) {
     this.nodeId = nodeId;
   }
-  
+
+  /** @since 4.0 */
   public NodeId getNodeId() {
     return nodeId;
   }
@@ -111,10 +113,12 @@ public class GraphvizNode {
     return ImmutableMap.copyOf(fields);
   }
 
+  /** @since 4.0 */
   public String getIdentifier() {
     return identifier;
   }
 
+  /** @since 4.0 */
   public void setIdentifier(String identifier) {
     this.identifier = identifier;
   }
diff --git a/extensions/jmx/src/com/google/inject/tools/jmx/package-info.java b/extensions/jmx/src/com/google/inject/tools/jmx/package-info.java
index 6bac97ff..e21f8648 100644
--- a/extensions/jmx/src/com/google/inject/tools/jmx/package-info.java
+++ b/extensions/jmx/src/com/google/inject/tools/jmx/package-info.java
@@ -15,6 +15,6 @@
  */
 
 /**
- * JMX integration; this extension requires {@code guice-jmx-3.0.jar}.
+ * JMX integration; this extension requires {@code guice-jmx.jar}.
  */
-package com.google.inject.tools.jmx;
\ No newline at end of file
+package com.google.inject.tools.jmx;
diff --git a/extensions/jndi/src/com/google/inject/jndi/package-info.java b/extensions/jndi/src/com/google/inject/jndi/package-info.java
index f6568ddb..f2f0af46 100644
--- a/extensions/jndi/src/com/google/inject/jndi/package-info.java
+++ b/extensions/jndi/src/com/google/inject/jndi/package-info.java
@@ -15,6 +15,6 @@
  */
 
 /**
- * JNDI integration; this extension requires {@code guice-jndi-3.0.jar}.
+ * JNDI integration; this extension requires {@code guice-jndi.jar}.
  */
-package com.google.inject.jndi;
\ No newline at end of file
+package com.google.inject.jndi;
diff --git a/extensions/multibindings/src/com/google/inject/multibindings/Multibinder.java b/extensions/multibindings/src/com/google/inject/multibindings/Multibinder.java
index 5491308d..f3fd552b 100644
--- a/extensions/multibindings/src/com/google/inject/multibindings/Multibinder.java
+++ b/extensions/multibindings/src/com/google/inject/multibindings/Multibinder.java
@@ -162,6 +162,7 @@ public abstract class Multibinder<T> {
   /**
    * Returns a new multibinder that collects instances of the key's type in a {@link Set} that is
    * itself bound with the annotation (if any) of the key.
+   *
    * @since 4.0
    */
   public static <T> Multibinder<T> newSetBinder(Binder binder, Key<T> key) {
diff --git a/extensions/multibindings/src/com/google/inject/multibindings/StringMapKey.java b/extensions/multibindings/src/com/google/inject/multibindings/StringMapKey.java
index 4cf0eccb..9a4f1bda 100644
--- a/extensions/multibindings/src/com/google/inject/multibindings/StringMapKey.java
+++ b/extensions/multibindings/src/com/google/inject/multibindings/StringMapKey.java
@@ -25,6 +25,7 @@ import java.lang.annotation.Target;
 
 /**
  * Allows {@literal @}{@link ProvidesIntoMap} to specify a string map key.
+ *
  * @since 4.0
  */
 @MapKey(unwrapValue = true)
diff --git a/extensions/multibindings/src/com/google/inject/multibindings/package-info.java b/extensions/multibindings/src/com/google/inject/multibindings/package-info.java
index f91c517c..71517791 100644
--- a/extensions/multibindings/src/com/google/inject/multibindings/package-info.java
+++ b/extensions/multibindings/src/com/google/inject/multibindings/package-info.java
@@ -16,6 +16,6 @@
 
 /**
  * Extension for binding multiple instances in a collection; this extension requires {@code
- * guice-multibindings-3.0.jar}.
+ * guice-multibindings.jar}.
  */
-package com.google.inject.multibindings;
\ No newline at end of file
+package com.google.inject.multibindings;
diff --git a/extensions/persist/src/com/google/inject/persist/jpa/JpaPersistModule.java b/extensions/persist/src/com/google/inject/persist/jpa/JpaPersistModule.java
index 027a0180..e9996c03 100644
--- a/extensions/persist/src/com/google/inject/persist/jpa/JpaPersistModule.java
+++ b/extensions/persist/src/com/google/inject/persist/jpa/JpaPersistModule.java
@@ -91,7 +91,8 @@ public final class JpaPersistModule extends PersistModule {
    * Configures the JPA persistence provider with a set of properties.
    * 
    * @param properties A set of name value pairs that configure a JPA persistence
-   * provider as per the specification.
+   *     provider as per the specification.
+   * @since 4.0 (since 3.0 with a parameter type of {@code java.util.Properties})
    */
   public JpaPersistModule properties(Map<?,?> properties) {
     this.properties = properties;
diff --git a/extensions/persist/src/com/google/inject/persist/package-info.java b/extensions/persist/src/com/google/inject/persist/package-info.java
index 510fc7e7..ed15e84f 100644
--- a/extensions/persist/src/com/google/inject/persist/package-info.java
+++ b/extensions/persist/src/com/google/inject/persist/package-info.java
@@ -16,6 +16,6 @@
 
 /**
  * Guice Persist: a lightweight persistence library for Guice; this extension requires {@code
- * guice-persist-3.0.jar}.
+ * guice-persist.jar}.
  */
-package com.google.inject.persist;
\ No newline at end of file
+package com.google.inject.persist;
diff --git a/extensions/servlet/src/com/google/inject/servlet/package-info.java b/extensions/servlet/src/com/google/inject/servlet/package-info.java
index c8caae0f..53f27465 100644
--- a/extensions/servlet/src/com/google/inject/servlet/package-info.java
+++ b/extensions/servlet/src/com/google/inject/servlet/package-info.java
@@ -16,10 +16,10 @@
 
 /**
  * Servlet API scopes, bindings and registration; this extension requires {@code
- * guice-servlet-3.0.jar}.
+ * guice-servlet.jar}.
  *
  * <p>Apply {@link com.google.inject.servlet.GuiceFilter} to any servlets which will use the servlet
  * scopes. Install {@link com.google.inject.servlet.ServletModule} into your {@link
  * com.google.inject.Injector} to install everything at once.
  */
-package com.google.inject.servlet;
\ No newline at end of file
+package com.google.inject.servlet;
diff --git a/extensions/spring/src/com/google/inject/spring/package-info.java b/extensions/spring/src/com/google/inject/spring/package-info.java
index 91bba099..42ca1c2d 100644
--- a/extensions/spring/src/com/google/inject/spring/package-info.java
+++ b/extensions/spring/src/com/google/inject/spring/package-info.java
@@ -15,6 +15,6 @@
  */
 
 /**
- * Spring integration; this extension requires {@code guice-spring-3.0.jar}.
+ * Spring integration; this extension requires {@code guice-spring.jar}.
  */
-package com.google.inject.spring;
\ No newline at end of file
+package com.google.inject.spring;
diff --git a/extensions/throwingproviders/src/com/google/inject/throwingproviders/CheckedProvides.java b/extensions/throwingproviders/src/com/google/inject/throwingproviders/CheckedProvides.java
index c7bfaedc..b4016209 100644
--- a/extensions/throwingproviders/src/com/google/inject/throwingproviders/CheckedProvides.java
+++ b/extensions/throwingproviders/src/com/google/inject/throwingproviders/CheckedProvides.java
@@ -45,7 +45,9 @@ public @interface CheckedProvides {
 
   /**
    * Whether exceptions should be put into the Guice scope.
-   * Default behavior is that exceptions are scoped. 
+   * Default behavior is that exceptions are scoped.
+   *
+   * @since 4.0
    */
   boolean scopeExceptions() default true;  
 }
diff --git a/extensions/throwingproviders/src/com/google/inject/throwingproviders/ThrowingProviderBinder.java b/extensions/throwingproviders/src/com/google/inject/throwingproviders/ThrowingProviderBinder.java
index 24cbd26c..546a242e 100644
--- a/extensions/throwingproviders/src/com/google/inject/throwingproviders/ThrowingProviderBinder.java
+++ b/extensions/throwingproviders/src/com/google/inject/throwingproviders/ThrowingProviderBinder.java
@@ -186,6 +186,7 @@ public class ThrowingProviderBinder {
 
     /**
      * Determines if exceptions should be scoped. By default exceptions are scoped.
+     *
      * @param scopeExceptions whether exceptions should be scoped.
      * @since 4.0
      */
@@ -203,11 +204,13 @@ public class ThrowingProviderBinder {
     public ScopedBindingBuilder to(Class<? extends P> targetType) {
       return to(Key.get(targetType));
     }
-    
+
+    /** @since 4.0 */
     public ScopedBindingBuilder providing(Class<? extends T> cxtorClass) {
       return providing(TypeLiteral.get(cxtorClass));
     }
-    
+
+    /** @since 4.0 */
     @SuppressWarnings("unchecked") // safe because this is the cxtor of the literal
     public ScopedBindingBuilder providing(TypeLiteral<? extends T> cxtorLiteral) {     
       // Find a constructor that has @ThrowingInject.
diff --git a/extensions/throwingproviders/src/com/google/inject/throwingproviders/package-info.java b/extensions/throwingproviders/src/com/google/inject/throwingproviders/package-info.java
index 2107ed14..29361f7f 100644
--- a/extensions/throwingproviders/src/com/google/inject/throwingproviders/package-info.java
+++ b/extensions/throwingproviders/src/com/google/inject/throwingproviders/package-info.java
@@ -16,6 +16,6 @@
 
 /**
  * Extension for injecting objects that may throw at provision time; this extension requires {@code
- * guice-throwingproviders-3.0.jar}.
+ * guice-throwingproviders.jar}.
  */
-package com.google.inject.throwingproviders;
\ No newline at end of file
+package com.google.inject.throwingproviders;