Documentation improvements for the constructors.

Improving documentation for the constructors and making
it clear that - for the moment - different usernames and
bucketnames are not possible.

Change-Id: I9e130f05009a888031cad76a76dc1fcc0f7411dd
Reviewed-on: http://review.couchbase.org/21217
Reviewed-by: Michael Wiederhold <mike@couchbase.com>
Reviewed-by: Matt Ingenthron <matt@couchbase.com>
Tested-by: Michael Wiederhold <mike@couchbase.com>

src/main/java/com/couchbase/client/CouchbaseClient.java

@@ -91,6 +91,12 @@
 
 /**
  * A client for Couchbase Server.
+ *
+ * This class acts as your main entry point while working with your Couchbase
+ * cluster (if you want to work with TAP, see the TapClient instead).
+ *
+ * If you are working with Couchbase Server 2.0, remember to set the appropriate
+ * view mode depending on your environment.
  */
 public class CouchbaseClient extends MemcachedClient
   implements CouchbaseClientIF, Reconfigurable {
@@ -153,16 +159,14 @@ public class CouchbaseClient extends MemcachedClient
   }
 
   /**
-   * Get a CouchbaseClient based on the REST response from a Couchbase server.
-   *
-   * This constructor is merely a convenience for situations where the bucket
-   * name is the same as the user name. This is commonly the case.
+   * Get a CouchbaseClient based on the initial server list provided.
    *
-   * To connect to the "default" special bucket for a given cluster, use an
-   * empty string as the password.
+   * This constructor should be used if the bucket name is the same as the 
+   * username (which is normally the case). If your bucket does not have
+   * a password (likely the "default" bucket), use an empty string instead.
    *
-   * If a password has not been assigned to the bucket, it is typically an empty
-   * string.
+   * This method is only a convenience method so you don't have to create a
+   * CouchbaseConnectionFactory for yourself.
    *
    * @param baseList the URI list of one or more servers from the cluster
    * @param bucketName the bucket name in the cluster you wish to use
@@ -171,51 +175,60 @@ public class CouchbaseClient extends MemcachedClient
    * @throws ConfigurationException if the configuration provided by the server
    *           has issues or is not compatible
    */
-  public CouchbaseClient(List<URI> baseList, String bucketName, String pwd)
+  public CouchbaseClient(final List<URI> baseList, final String bucketName,
+    final String pwd)
     throws IOException {
     this(new CouchbaseConnectionFactory(baseList, bucketName, pwd));
   }
 
   /**
-   * Get a CouchbaseClient based on the REST response from a Couchbase server
-   * where the username is different than the bucket name.
+   * Get a CouchbaseClient based on the initial server list provided.
+   *
+   * Currently, Couchbase Server does not support a different username than the
+   * bucket name. Therefore, this method ignores the given username for now
+   * but will likely use it in the future.
    *
-   * To connect to the "default" special bucket for a given cluster, use an
-   * empty string as the password.
+   * This constructor should be used if the bucket name is NOT the same as the
+   * username. If your bucket does not have a password (likely the "default"
+   * bucket), use an empty string instead.
    *
-   * If a password has not been assigned to the bucket, it is typically an empty
-   * string.
+   * This method is only a convenience method so you don't have to create a
+   * CouchbaseConnectionFactory for yourself.
    *
    * @param baseList the URI list of one or more servers from the cluster
    * @param bucketName the bucket name in the cluster you wish to use
-   * @param usr the username for the bucket; this nearly always be the same as
-   *          the bucket name
+   * @param user the username for the bucket
    * @param pwd the password for the bucket
    * @throws IOException if connections could not be made
-   * @throws ConfigurationException if the configuration provided by
-   *          the server has issues or is not compatible
+   * @throws ConfigurationException if the configuration provided by the server
+   *           has issues or is not compatible
    */
   public CouchbaseClient(final List<URI> baseList, final String bucketName,
-      final String usr, final String pwd) throws IOException {
+    final String user, final String pwd)
+    throws IOException {
     this(new CouchbaseConnectionFactory(baseList, bucketName, pwd));
   }
 
   /**
-   * Get a CouchbaseClient based on the REST response from a Couchbase server
-   * where the username is different than the bucket name.
+   * Get a CouchbaseClient based on the settings from the given
+   * CouchbaseConnectionFactory.
    *
-   * Note that when specifying a ConnectionFactory you must specify a
-   * BinaryConnectionFactory. Also the ConnectionFactory's protocol and locator
-   * values are always overwritten. The protocol will always be binary and the
-   * locator will be chosen based on the bucket type you are connecting to.
+   * If your bucket does not have a password (likely the "default" bucket), use
+   * an empty string instead.
    *
-   * To connect to the "default" special bucket for a given cluster, use an
-   * empty string as the password.
+   * The URI list provided here is only used during the initial connection to
+   * the cluster. Afterwards, the actual cluster-map is synchronized from the
+   * cluster and maintained internally by the client. This allows the client to
+   * update the map as needed (when the cluster topology changes).
    *
-   * If a password has not been assigned to the bucket, it is typically an empty
-   * string.
+   * Note that when specifying a ConnectionFactory you must specify a
+   * BinaryConnectionFactory (which is the case if you use the
+   * CouchbaseConnectionFactory). Also the ConnectionFactory's protocol and 
+   * locator values are always overwritten. The protocol will always be binary 
+   * and the locator will be chosen based on the bucket type you are connecting 
+   * to.
    *
-   * The subscribe variable is determines whether or not we will subscribe to
+   * The subscribe variable determines whether or not we will subscribe to
    * the configuration changes feed. This constructor should be used when
    * calling super from subclasses of CouchbaseClient since the subclass might
    * want to start the changes feed later.