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