improve API reference on authentication

Improve documentation on authentication.  Why are there multiple methods?  Which one is the best one to use?  Are any deprecated?

Note that for instance, so me return values are mixed, which is pretty impossible to work with from an API perspective.

Forums thread with background: https://forums.couchbase.com/t/authentication-in-the-php-sdk-documentation-sources/11660