SASL, username and password related javadoc improvements

smack-core/src/main/java/org/jivesoftware/smack/AbstractXMPPConnection.java

@@ -424,8 +424,8 @@ public abstract class AbstractXMPPConnection implements XMPPConnection {
     }
 
     /**
-     * Login with the given username. You may omit the password if a callback handler is used. If
+     * Login with the given username (authorization identity). You may omit the password if a callback handler is used.
-     * resource is null, then the server will generate one.
+     * If resource is null, then the server will generate one.
      * 
      * @param username
      * @param password

smack-core/src/main/java/org/jivesoftware/smack/ConnectionConfiguration.java

@@ -419,11 +419,12 @@ public abstract class ConnectionConfiguration {
         /**
          * Set the XMPP entities username and password.
          * <p>
-         * The username is the localpart of the entities JID, e.g. <code>localpart@example.org</code>.
+         * The username is usually the localpart of the clients JID. But some SASL mechanisms or services may require a different
+         * format (e.g. the full JID) as used authorization identity.
          * </p>
          *
-         * @param username
+         * @param username the username or authorization identity
-         * @param password
+         * @param password the password or token used to authenticate
          * @return a reference to this builder.
          */
         public B setUsernameAndPassword(String username, String password) {

smack-core/src/main/java/org/jivesoftware/smack/sasl/SASLMechanism.java

@@ -91,9 +91,12 @@ public abstract class SASLMechanism implements Comparable<SASLMechanism> {
     protected XMPPConnection connection;
 
     /**
-     * authcid, i.e. the username (localpart) of the XMPP connection trying to authenticated.
+     * Then authentication identity (authcid). RFC 6120 § 6.3.7 informs us that some SASL mechanisms use this as a
+     * "simple user name". But the exact form is a matter of the mechanism and that it does not necessarily map to an
+     * localpart. But it usually is the localpart of the client JID, although sometimes other formats are used (e.g. the
+     * full JID).
      * <p>
-     * Not to be confused with the authzid.
+     * Not to be confused with the authzid (see RFC 6120 § 6.3.8).
      * </p>
      */
     protected String authenticationId;

smack-core/src/main/java/org/jivesoftware/smack/sasl/core/SASLXOauth2Mechanism.java

@@ -1,6 +1,6 @@
 /**
  *
- * Copyright 2014 Florian Schmaus
+ * Copyright 2014-2015 Florian Schmaus
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -30,8 +30,8 @@ import org.jivesoftware.smack.util.stringencoder.Base64;
  * The given password will be used as OAUTH token.
  * </p>
  * <p>
- * Note that X-OAUTH2 is experimental in Smack. This is because Google defined, besides being a bad practice, custom
+ * Note that X-OAUTH2 is experimental in Smack. This is because Google defined, besides being a bad practice (XEP-134),
- * attributes to the 'auth' stanze, as can be seen here
+ * custom attributes to the 'auth' stanza, as can be seen here
  * </p>
  * 
  * <pre>