docs(GoogleAuth): Document Credential Precedence (#1653)

src/auth/googleauth.ts

@@ -173,6 +173,17 @@ export class GoogleAuth<T extends AuthClient = JSONClient> {
    */
   static DefaultTransporter = DefaultTransporter;
 
+  /**
+   * Configuration is resolved in the following order of precedence:
+   * - {@link GoogleAuthOptions.credentials `credentials`}
+   * - {@link GoogleAuthOptions.keyFilename `keyFilename`}
+   * - {@link GoogleAuthOptions.keyFile `keyFile`}
+   *
+   * {@link GoogleAuthOptions.clientOptions `clientOptions`} are passed to the
+   * {@link AuthClient `AuthClient`s}.
+   *
+   * @param opts
+   */
   constructor(opts?: GoogleAuthOptions<T>) {
     opts = opts || {};
 
@@ -195,8 +206,13 @@ export class GoogleAuth<T extends AuthClient = JSONClient> {
 
   /**
    * Obtains the default project ID for the application.
-   * @param callback Optional callback
-   * @returns Promise that resolves with project Id (if used without callback)
+   *
+   * Retrieves in the following order of precedence:
+   * - The `projectId` provided in this object's construction
+   * - GCLOUD_PROJECT or GOOGLE_CLOUD_PROJECT environment variable
+   * - GOOGLE_APPLICATION_CREDENTIALS JSON file
+   * - Cloud SDK: `gcloud config config-helper --format json`
+   * - GCE project ID from metadata server
    */
   getProjectId(): Promise<string>;
   getProjectId(callback: ProjectIdCallback): void;
@@ -900,8 +916,9 @@ export class GoogleAuth<T extends AuthClient = JSONClient> {
   }
 
   /**
-   * Automatically obtain a client based on the provided configuration.  If no
-   * options were passed, use Application Default Credentials.
+   * Automatically obtain an {@link AuthClient `AuthClient`} based on the
+   * provided configuration. If no options were passed, use Application
+   * Default Credentials.
    */
   async getClient() {
     if (!this.cachedCredential) {