who wants more javadoc?
git-svn-id: https://google-guice.googlecode.com/svn/trunk@236 d779f126-a31b-0410-b53b-1d3aecad763e
diff --git a/src/com/google/inject/Binder.java b/src/com/google/inject/Binder.java
index af7c0eb..611026d 100644
--- a/src/com/google/inject/Binder.java
+++ b/src/com/google/inject/Binder.java
@@ -9,7 +9,11 @@
import org.aopalliance.intercept.MethodInterceptor;
/**
- * Used by {@link Module} implementations to configure bindings.
+ * Collect configuration data (primarily <i>bindings</i>) from one or more
+ * modules, so that this collected information may then be used to construct a
+ * new container. There is no public API to create an instance of this
+ * interface; instead, your {@link Module} implementations will simply have one
+ * passed in automatically.
*/
public interface Binder {
diff --git a/src/com/google/inject/Binding.java b/src/com/google/inject/Binding.java
index c423cac..d55c3cd 100644
--- a/src/com/google/inject/Binding.java
+++ b/src/com/google/inject/Binding.java
@@ -17,25 +17,28 @@
package com.google.inject;
/**
- * A binding from a {@link Key} (type and name) to a provider.
+ * A mapping from a key (type and optional annotation) to a provider of
+ * instances of that type. This interface is part of the container
+ * introspection API and is intended primary for use by tools.
*
* @author crazybob@google.com (Bob Lee)
*/
public interface Binding<T> {
/**
- * Gets the key for this binding.
+ * Returns the key for this binding.
*/
Key<T> getKey();
/**
- * Gets the source object, an arbitrary object which points back to the
- * configuration which resulted in this binding.
+ * Returns an arbitrary object containing information about the "place" where
+ * this binding was configured. Used by guice in the production of descriptive
+ * error messages.
*/
Object getSource();
/**
- * Gets the provider which returns instances of {@code T}.
+ * Returns the provider guice uses to fulfill requests for this binding.
*/
Provider<T> getProvider();
}
diff --git a/src/com/google/inject/Container.java b/src/com/google/inject/Container.java
index 9ad642d..66bcea5 100644
--- a/src/com/google/inject/Container.java
+++ b/src/com/google/inject/Container.java
@@ -20,26 +20,29 @@
import java.util.Map;
/**
- * Injects dependencies into constructors, methods and fields annotated with
- * {@code @}{@link Inject}. Iterates explicit {@link Binding}s.
+ * The container fulfills requests for the object instances that make up your
+ * application, always ensuring that these instances are properly injected
+ * before they are returned. The container is the heart of the Guice framework,
+ * although you don't typically interact with it directly very often. This
+ * "behind-the-scenes" operation is what distinguishes the Dependency Injection
+ * pattern from its cousin, Service Locator.
*
- * <p>Automatically converts constant values as needed from {@code String} to
- * any primitive type in addition to {@code enum} and {@code Class<?>}.
- * Automatically boxes and unboxes primitives. For example, in the absence of
- * a binding to {@code int}, the container will look for a binding to {@code
- * Integer}.
+ * <p>The Container API has a few additional features: it allows pre-constructed
+ * instances to have their fields and methods injected, and offers programmatic
+ * introspection to support tool development.
*
* <p>Contains several default bindings:
*
* <ul>
- * <li>This {@link Container}
+ * <li>This {@link Container} instance itself
* <li>A {@code Provider<T>} for each binding of type {@code T}
* <li>The {@link java.util.logging.Logger} for the class being injected
* <li>The {@link Stage} specified when this container was created
* </ul>
*
+ * Containers are created using the facade class {@link Guice}.
+ *
* @author crazybob@google.com (Bob Lee)
- * @see Guice
*/
public interface Container {
diff --git a/src/com/google/inject/Module.java b/src/com/google/inject/Module.java
index 9dfde3e..7c50a06 100644
--- a/src/com/google/inject/Module.java
+++ b/src/com/google/inject/Module.java
@@ -17,15 +17,13 @@
package com.google.inject;
/**
- * A module contributes a set of binding configurations, typically interface
- * bindings, to a {@link Binder} which is later used to create a {@link
- * Container}. Implementing this interface is the standard means for
- * encapsulating and reusing configuration logic.
+ * A module contributes a set of configuration data, typically interface
+ * bindings, which will be used to create a {@link Container}. A guice-based
+ * application is ultimately composed of little but a set of Modules and some
+ * bootstrapping code.
*
* <p>Your Module classes can use a more streamlined syntax by extending
* {@link AbstractModule} rather than implementing this interface directly.
- *
- * @since 1.0
*/
public interface Module {
diff --git a/src/com/google/inject/Provider.java b/src/com/google/inject/Provider.java
index 5fc2a41..6713364 100644
--- a/src/com/google/inject/Provider.java
+++ b/src/com/google/inject/Provider.java
@@ -17,7 +17,32 @@
package com.google.inject;
/**
- * Provides instances of {@code T}.
+ * Simply, any object capable of providing instances of type {@code T}.
+ * Providers are used in numerous ways by the guice framework:
+ *
+ * <ul>
+ * <li>When the default means for obtaining instances (an injectable or
+ * parameterless constructor) is insufficient for a particular binding, the
+ * module can specify a custom Provider instead, to control exactly how guice
+ * creates or obtains instances for the binding.
+ *
+ * <li>An implementation class may always choose to have a {@code Provider<T>}
+ * instance injected, rather than having a {@code T} injected directly. This
+ * may give you access to multiple instances, instances you wish to safely
+ * mutate and discard, instances which are out of scope (e.g. using a
+ * request-scoped object from within a container-scoped object), or instances
+ * you don't want to initialize until they are absolutely needed.
+ *
+ * <li>A custom {@link Scope} is implemented as a decorator of
+ * {@code Provider<T>}, which decides when to delegate to the backing provider
+ * and when to provide the instance some other way.
+ *
+ * <li>The {@link Container} offers access to the {@code Provider<T>} it uses
+ * to fulfill requests for a given key, via the {@link Container#getProvider}
+ * methods.
+ * </ul>
+ *
+ * @param <T> the type of object this provider provides
*
* @author crazybob@google.com (Bob Lee)
*/
diff --git a/src/com/google/inject/Scope.java b/src/com/google/inject/Scope.java
index 8ef6e07..61871ef 100644
--- a/src/com/google/inject/Scope.java
+++ b/src/com/google/inject/Scope.java
@@ -17,12 +17,14 @@
package com.google.inject;
/**
- * A scope which bound objects can reside in. Scopes a given {@link Provider}.
+ * A scope is a level of visibility that instances provided by Guice may have.
+ * By default, instances created by the Guice container have <i>no scope</i>,
+ * meaning they have no visibility -- guice creates them, injects them once,
+ * then immediately forgets them. Associating a scope with a particular binding
+ * allows the created instance to be "remembered" and possibly used again for
+ * other injections.
*
- * <p>Scope implementations should override {@code toString()} in the returned
- * provider and include the unscoped provider's {@code toString()} output. Doing
- * so aids debugging. They should also override their own {@code toString()}
- * method.
+ * @see Scopes#CONTAINER
*
* @author crazybob@google.com (Bob Lee)
*/
@@ -33,6 +35,10 @@
* an object does not exist in this scope, the provider can use the given
* unscoped provider to retrieve one.
*
+ * <p>Scope implementations are strongly encouraged to override
+ * {@link Object#toString} in the returned provider and include the backing
+ * provider's {@code toString()} output.
+ *
* @param key binding key
* @param unscoped locates an instance when one doesn't already exist in this
* scope.
@@ -41,4 +47,11 @@
* scope
*/
public <T> Provider<T> scope(Key<T> key, Provider<T> unscoped);
+
+ /**
+ * A short but useful description of this scope. For comparison, the standard
+ * scopes that ship with guice use the descriptions {@code "Scopes.CONTAINER"},
+ * {@code "ServletScopes.SESSION"} and {@code "ServletScopes.REQUEST"}.
+ */
+ String toString();
}
