Add more info to getToken() method (Azure#15788)

* Add more info to getToken() method

* Fix javadocs

* Improve doc wording on ChainedTokenCredential

Author: jianghaolu

sdk/core/azure-core/src/main/java/com/azure/core/credential/TokenCredential.java

@@ -12,6 +12,11 @@
 public interface TokenCredential {
     /**
      * Asynchronously get a token for a given resource/audience.
+     *
+     * This method is called automatically by Azure SDK client libraries.
+     * You may call this method directly, but you must also handle token
+     * caching and token refreshing.
+     *
      * @param request the details of the token request
      * @return a Publisher that emits a single access token
      */

sdk/identity/azure-identity/src/main/java/com/azure/identity/ChainedTokenCredential.java

@@ -37,6 +37,17 @@ public class ChainedTokenCredential implements TokenCredential {
         this.credentials = Collections.unmodifiableList(credentials);
     }
 
+    /**
+     * Sequentially calls {@link TokenCredential#getToken(TokenRequestContext)} on all the specified credentials,
+     * returning the first successfully obtained {@link AccessToken}.
+     *
+     * This method is called automatically by Azure SDK client libraries.
+     * You may call this method directly, but you must also handle token
+     * caching and token refreshing.
+     *
+     * @param request the details of the token request
+     * @return a Publisher that emits a single access token
+     */
     @Override
     public Mono<AccessToken> getToken(TokenRequestContext request) {
         List<CredentialUnavailableException> exceptions = new ArrayList<>(4);