diff --git a/blobstore/src/main/java/org/jclouds/blobstore/BlobStoreContextFactory.java b/blobstore/src/main/java/org/jclouds/blobstore/BlobStoreContextFactory.java
index f663d220bf..e014115fe1 100644
--- a/blobstore/src/main/java/org/jclouds/blobstore/BlobStoreContextFactory.java
+++ b/blobstore/src/main/java/org/jclouds/blobstore/BlobStoreContextFactory.java
@@ -31,9 +31,17 @@ import com.google.common.collect.ImmutableSet;
 import com.google.inject.Module;
 
 /**
+ * This class is deprecated in favor of {@link ContextBuilder}. Please view
+ * sample usage below:
+ * 
+ * <pre>
+ * context = ContextBuilder.newBuilder("aws-s3")
+ *                         .credentials(apikey, secret)
+ *                         .buildView(BlobStoreContext.class);
+ * </pre>
  * 
  * @see ContextBuilder
- * @see BlobStoreContextBuilder
+ * @deprecated  As of version 1.5, replaced by {@link ContextBuilder}
  * @author Adrian Cole
  */
 @Deprecated
diff --git a/compute/src/main/java/org/jclouds/compute/ComputeServiceContextFactory.java b/compute/src/main/java/org/jclouds/compute/ComputeServiceContextFactory.java
index 30b697a25d..bc10f57c5f 100644
--- a/compute/src/main/java/org/jclouds/compute/ComputeServiceContextFactory.java
+++ b/compute/src/main/java/org/jclouds/compute/ComputeServiceContextFactory.java
@@ -31,9 +31,19 @@ import com.google.common.collect.ImmutableSet;
 import com.google.inject.Module;
 
 /**
+ * This class is deprecated in favor of {@link ContextBuilder}. Please view
+ * sample usage below:
+ * 
+ * <pre>
+ * context = ContextBuilder.newBuilder("openstack-nova")
+ *                         .endpoint("http://10.10.10.10:5000/v2.0")
+ *                         .credentials(user, pass)
+ *                         .modules(singleton(new SshjSshClientModule()))
+ *                         .buildView(ComputeServiceContext.class);
+ * </pre>
  * 
  * @see ContextBuilder
- * @see ComputeServiceContextBuilder
+ * @deprecated  As of version 1.5, replaced by {@link ContextBuilder}
  * @author Adrian Cole
  */
 @Deprecated
diff --git a/core/src/main/java/org/jclouds/ContextBuilder.java b/core/src/main/java/org/jclouds/ContextBuilder.java
index 2867f450ed..aac882d3a9 100644
--- a/core/src/main/java/org/jclouds/ContextBuilder.java
+++ b/core/src/main/java/org/jclouds/ContextBuilder.java
@@ -91,17 +91,46 @@ import com.google.inject.Stage;
 import com.google.inject.TypeLiteral;
 
 /**
- * Creates {@link RestContext} or {@link Injector} instances based on the most commonly requested
- * arguments.
+ * Creates {@link Context} or {@link Injector} configured to an api and
+ * endpoint. Alternatively, this can be used to make a portable {@link View} of
+ * that api.
+ * 
+ * <br/>
+ * ex. to build a {@link RestContext} on a particular endpoint using the typed
+ * interface
+ * 
+ * <pre>
+ * context = ContextBuilder.newBuilder(new NovaApiMetadata())
+ *                         .endpoint("http://10.10.10.10:5000/v2.0")
+ *                         .credentials(user, pass)
+ *                         .build(NovaApiMetadata.CONTEXT_TOKEN)
+ * </pre>
+ * 
+ * <br/>
+ * ex. to build a {@link View} of a particular backend context, looked up by
+ * key.
+ * 
+ * <pre>
+ * context = ContextBuilder.newBuilder("aws-s3")
+ *                         .credentials(apikey, secret)
+ *                         .buildView(BlobStoreContext.class);
+ * </pre>
+ * 
+ * <h4>Assumptions</h4>
+ * 
+ * Threadsafe objects will be bound as singletons to the Injector or Context
+ * provided.
  * <p/>
- * Note that Threadsafe objects will be bound as singletons to the Injector or Context provided.
- * <p/>
- * <p/>
- * If no <code>Module</code>s are specified, the default {@link JDKLoggingModule logging} and
- * {@link JavaUrlHttpCommandExecutorServiceModule http transports} will be installed.
+ * If no <code>Module</code>s are specified, the default
+ * {@link JDKLoggingModule logging} and
+ * {@link JavaUrlHttpCommandExecutorServiceModule http transports} will be
+ * installed.
  * 
  * @author Adrian Cole, Andrew Newdigate
- * @see RestContext
+ * @see Context
+ * @see View
+ * @see ApiMetadata
+ * @see ProviderMetadata
  */
 public class ContextBuilder {
 
diff --git a/loadbalancer/src/main/java/org/jclouds/loadbalancer/LoadBalancerServiceContextFactory.java b/loadbalancer/src/main/java/org/jclouds/loadbalancer/LoadBalancerServiceContextFactory.java
index 4ddc31a067..16a329c1d5 100644
--- a/loadbalancer/src/main/java/org/jclouds/loadbalancer/LoadBalancerServiceContextFactory.java
+++ b/loadbalancer/src/main/java/org/jclouds/loadbalancer/LoadBalancerServiceContextFactory.java
@@ -31,9 +31,17 @@ import com.google.common.collect.ImmutableSet;
 import com.google.inject.Module;
 
 /**
+ * This class is deprecated in favor of {@link ContextBuilder}. Please view
+ * sample usage below:
+ * 
+ * <pre>
+ * context = ContextBuilder.newBuilder("aws-elb")
+ *                         .credentials(apikey, secret)
+ *                         .buildView(LoadBalancerServiceContext.class);
+ * </pre>
  * 
  * @see ContextBuilder
- * @see LoadBalancerServiceContextBuilder
+ * @deprecated  As of version 1.5, replaced by {@link ContextBuilder}
  * @author Adrian Cole
  */
 @Deprecated