[Identity] Clearer message on the getToken methods

[sadasant]

Since some of our customers have started to work with our credentials directly, we've agreed that we should let them know that if they decide to work with the getToken methods themselves, they will need to figure out caching and token refreshing.

Fixes #11343

The specific message the team wants to add is this one:

// 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.

The main change here is an extra comment on both ChainedTokenCredential and TokenCredential to help users see this if they decide to use any of both directly. DefaultAzureCredential gets automatically handled by ChainedTokenCredential since the method is inherited.

Feedback always appreciated 🙌❤

[joheredi]

How often do you think this is used by mistake rather than by real need? If most of the time it is by mistake would it make sense to log a Warning as well?

Also can we point to a sample that shows a common scenario where users may be tempted to call this and show the better option?

[sadasant]

@joheredi I'm not sure if pointing to a concrete scenario makes sense. The idea is not to publicize this use case, rather to avoid confusion in case users end up working with these internals themselves.

@jianghaolu what do you think of Jose's idea? (comment above)

[joheredi]

@joheredi I'm not sure if pointing to a concrete scenario makes sense. The idea is not to publicize this use case, rather to avoid confusion in case users end up working with these internals themselves.

@jianghaolu what do you think of Jose's idea? (comment above)

I was thinking more on a sample discouraging the use of these internals and showing the recommended way.

Of course these suggestions wouldn't block this PR at all, just wanted to bring them up in case we find it useful to be more proactive in notifying the user.

[jianghaolu]

In .NET and Python SDK today we have this in the doc: "This method is called by Azure SDK clients. It isn't intended for use in application code." and we have customers complaining this has discouraged their valid use case - thus we decided to loosen it a little bit. With that being said, I agree most use cases should not involve calling this method directly, thus a sample could be helpful here.

[sadasant]

Thank you all! I'm merging.