[Auth] Update documentation to fill gaps

common/api-review/auth-exp.api.md

@@ -185,20 +185,17 @@ export const debugErrorMap: AuthErrorMap;
 // @public
 export function deleteUser(user: User): Promise<void>;
 
-// @public (undocumented)
+// @public
 export interface Dependencies {
-    // (undocumented)
     errorMap?: AuthErrorMap;
-    // (undocumented)
     persistence?: Persistence | Persistence[];
-    // (undocumented)
     popupRedirectResolver?: PopupRedirectResolver;
 }
 
 // @public
 export class EmailAuthCredential extends AuthCredential {
-    // (undocumented)
-    readonly email: string;
+    // @internal (undocumented)
+    readonly _email: string;
     // @internal (undocumented)
     static _fromEmailAndCode(email: string, oobCode: string, tenantId?: string | null): EmailAuthCredential;
     // @internal (undocumented)
@@ -210,10 +207,10 @@ export class EmailAuthCredential extends AuthCredential {
     _getReauthenticationResolver(auth: AuthInternal): Promise<IdTokenResponse>;
     // @internal (undocumented)
     _linkToIdToken(auth: AuthInternal, idToken: string): Promise<IdTokenResponse>;
-    // (undocumented)
-    readonly password: string;
-    // (undocumented)
-    readonly tenantId: string | null;
+    // @internal (undocumented)
+    readonly _password: string;
+    // @internal (undocumented)
+    readonly _tenantId: string | null;
     toJSON(): object;
 }
 
@@ -253,7 +250,7 @@ export function fetchSignInMethodsForEmail(auth: Auth, email: string): Promise<s
 export function getAdditionalUserInfo(userCredential: UserCredential): AdditionalUserInfo | null;
 
 // @public
-export function getAuth(app: FirebaseApp): Auth;
+export function getAuth(app?: FirebaseApp): Auth;
 
 // @public
 export function getIdToken(user: User, forceRefresh?: boolean): Promise<string>;
@@ -301,7 +298,7 @@ export interface IdTokenResult {
 // @public
 export const indexedDBLocalPersistence: Persistence;
 
-// @public (undocumented)
+// @public
 export function initializeAuth(app: FirebaseApp, deps?: Dependencies): Auth;
 
 // @public
@@ -397,7 +394,6 @@ export interface OAuthCredentialOptions {
 export class OAuthProvider extends BaseOAuthProvider {
     credential(params: OAuthCredentialOptions): OAuthCredential;
     static credentialFromError(error: FirebaseError): OAuthCredential | null;
-    // (undocumented)
     static credentialFromJSON(json: object | string): OAuthCredential;
     static credentialFromResult(userCredential: UserCredential): OAuthCredential | null;
     }
@@ -415,7 +411,7 @@ export const enum OperationType {
     SIGN_IN = "signIn"
 }
 
-// @public (undocumented)
+// @public
 export function parseActionCodeURL(link: string): ActionCodeURL | null;
 
 // @public
@@ -438,9 +434,6 @@ export interface Persistence {
 
 // @public
 export class PhoneAuthCredential extends AuthCredential {
-    // Warning: (ae-unresolved-inheritdoc-reference) The @inheritDoc reference could not be resolved: No member was found with name "fromJSON"
-    //
-    // (undocumented)
     static fromJSON(json: object | string): PhoneAuthCredential | null;
     // @internal (undocumented)
     static _fromTokenResponse(phoneNumber: string, temporaryProof: string): PhoneAuthCredential;
@@ -463,7 +456,6 @@ export class PhoneAuthCredential extends AuthCredential {
 export class PhoneAuthProvider {
     constructor(auth: Auth);
     static credential(verificationId: string, verificationCode: string): PhoneAuthCredential;
-    // (undocumented)
     static credentialFromResult(userCredential: UserCredential): AuthCredential | null;
     static readonly PHONE_SIGN_IN_METHOD = SignInMethod.PHONE;
     static readonly PROVIDER_ID = ProviderId.PHONE;
@@ -510,23 +502,17 @@ export const prodErrorMap: AuthErrorMap;
 
 // @public
 export const enum ProviderId {
-    // (undocumented)
+    // @internal (undocumented)
     ANONYMOUS = "anonymous",
-    // (undocumented)
+    // @internal (undocumented)
     CUSTOM = "custom",
-    // (undocumented)
     FACEBOOK = "facebook.com",
-    // (undocumented)
+    // @internal (undocumented)
     FIREBASE = "firebase",
-    // (undocumented)
     GITHUB = "github.com",
-    // (undocumented)
     GOOGLE = "google.com",
-    // (undocumented)
     PASSWORD = "password",
-    // (undocumented)
     PHONE = "phone",
-    // (undocumented)
     TWITTER = "twitter.com"
 }
 
@@ -575,11 +561,8 @@ export function reload(user: User): Promise<void>;
 // @public
 export class SAMLAuthProvider extends FederatedAuthProvider {
     constructor(providerId: string);
-    // (undocumented)
     static credentialFromError(error: FirebaseError): AuthCredential | null;
-    // (undocumented)
     static credentialFromJSON(json: string | object): AuthCredential;
-    // (undocumented)
     static credentialFromResult(userCredential: UserCredential): AuthCredential | null;
     }
 
@@ -590,7 +573,7 @@ export function sendEmailVerification(user: User, actionCodeSettings?: ActionCod
 export function sendPasswordResetEmail(auth: Auth, email: string, actionCodeSettings?: ActionCodeSettings): Promise<void>;
 
 // @public
-export function sendSignInLinkToEmail(auth: Auth, email: string, actionCodeSettings?: ActionCodeSettings): Promise<void>;
+export function sendSignInLinkToEmail(auth: Auth, email: string, actionCodeSettings: ActionCodeSettings): Promise<void>;
 
 // @public
 export function setPersistence(auth: Auth, persistence: Persistence): Promise<void>;
@@ -600,21 +583,14 @@ export function signInAnonymously(auth: Auth): Promise<UserCredential>;
 
 // @public
 export const enum SignInMethod {
-    // (undocumented)
+    // @internal (undocumented)
     ANONYMOUS = "anonymous",
-    // (undocumented)
     EMAIL_LINK = "emailLink",
-    // (undocumented)
     EMAIL_PASSWORD = "password",
-    // (undocumented)
     FACEBOOK = "facebook.com",
-    // (undocumented)
     GITHUB = "github.com",
-    // (undocumented)
     GOOGLE = "google.com",
-    // (undocumented)
     PHONE = "phone",
-    // (undocumented)
     TWITTER = "twitter.com"
 }
 
@@ -648,9 +624,7 @@ export class TwitterAuthProvider extends BaseOAuthProvider {
     static credential(token: string, secret: string): OAuthCredential;
     static credentialFromError(error: FirebaseError): OAuthCredential | null;
     static credentialFromResult(userCredential: UserCredential): OAuthCredential | null;
-    // (undocumented)
     static readonly PROVIDER_ID = ProviderId.TWITTER;
-    // (undocumented)
     static readonly TWITTER_SIGN_IN_METHOD = SignInMethod.TWITTER;
 }
 

packages-exp/auth-exp/src/core/action_code_url.ts

@@ -154,7 +154,8 @@ export class ActionCodeURL {
 }
 
 /**
- * {@inheritDoc @firebase/auth-types#ActionCodeURL.parseLink}
+ * Parses the email action link string and returns an {@link ActionCodeURL} if
+ * the link is valid, otherwise returns null.
  *
  * @public
  */

packages-exp/auth-exp/src/core/auth/initialize.ts

@@ -24,7 +24,31 @@ import { _fail } from '../util/assert';
 import { _getInstance } from '../util/instantiator';
 import { AuthImpl } from './auth_impl';
 
-/** @public */
+/**
+ * Initializes an Auth instance with fine-grained control over
+ * {@link Dependencies}.
+ *
+ * @remarks
+ *
+ * This function allows more control over the Auth instance than
+ * {@link getAuth}. `getAuth` uses platform-specific defaults to supply
+ * the {@link Dependencies}. In general, `getAuth` is the easiest way to
+ * initialize Auth and works for most use cases. Use `initializeAuth` if you
+ * need control over which persistence layer is used, or to minimize bundle
+ * size if you're not using either `signInWithPopup` or `signInWithRedirect`.
+ *
+ * For example, if your app only uses anonymous accounts and you only want
+ * accounts saved for the current session, initialize Auth with:
+ *
+ * ```js
+ * const auth = initializeAuth(app, {
+ *   persistence: browserSessionPersistence,
+ *   popupRedirectResolver: undefined,
+ * });
+ * ```
+ *
+ * @public
+ */
 export function initializeAuth(app: FirebaseApp, deps?: Dependencies): Auth {
   const provider = _getProvider(app, 'auth-exp');
 

packages-exp/auth-exp/src/core/credentials/email.ts

@@ -42,10 +42,13 @@ import { AuthCredential } from './auth_credential';
 export class EmailAuthCredential extends AuthCredential {
   /** @internal */
   private constructor(
-    readonly email: string,
-    readonly password: string,
+    /** @internal */
+    readonly _email: string,
+    /** @internal */
+    readonly _password: string,
     signInMethod: SignInMethod,
-    readonly tenantId: string | null = null
+    /** @internal */
+    readonly _tenantId: string | null = null
   ) {
     super(ProviderId.PASSWORD, signInMethod);
   }
@@ -79,10 +82,10 @@ export class EmailAuthCredential extends AuthCredential {
   /** {@inheritdoc AuthCredential.toJSON} */
   toJSON(): object {
     return {
-      email: this.email,
-      password: this.password,
+      email: this._email,
+      password: this._password,
       signInMethod: this.signInMethod,
-      tenantId: this.tenantId
+      tenantId: this._tenantId
     };
   }
 
@@ -112,13 +115,13 @@ export class EmailAuthCredential extends AuthCredential {
       case SignInMethod.EMAIL_PASSWORD:
         return signInWithPassword(auth, {
           returnSecureToken: true,
-          email: this.email,
-          password: this.password
+          email: this._email,
+          password: this._password
         });
       case SignInMethod.EMAIL_LINK:
         return signInWithEmailLink(auth, {
-          email: this.email,
-          oobCode: this.password
+          email: this._email,
+          oobCode: this._password
         });
       default:
         _fail(auth, AuthErrorCode.INTERNAL_ERROR);
@@ -135,14 +138,14 @@ export class EmailAuthCredential extends AuthCredential {
         return updateEmailPassword(auth, {
           idToken,
           returnSecureToken: true,
-          email: this.email,
-          password: this.password
+          email: this._email,
+          password: this._password
         });
       case SignInMethod.EMAIL_LINK:
         return signInWithEmailLinkForLinking(auth, {
           idToken,
-          email: this.email,
-          oobCode: this.password
+          email: this._email,
+          oobCode: this._password
         });
       default:
         _fail(auth, AuthErrorCode.INTERNAL_ERROR);

packages-exp/auth-exp/src/core/credentials/phone.ts

@@ -121,7 +121,7 @@ export class PhoneAuthCredential extends AuthCredential {
     return obj;
   }
 
-  /** {@inheritdoc AuthCredential.fromJSON} */
+  /** Generates a phone credential based on a plain object or a JSON string. */
   static fromJSON(json: object | string): PhoneAuthCredential | null {
     if (typeof json === 'string') {
       json = JSON.parse(json);

packages-exp/auth-exp/src/core/providers/email.test.ts

@@ -33,8 +33,8 @@ describe('core/providers/email', () => {
         'some-email',
         'some-password'
       );
-      expect(credential.email).to.eq('some-email');
-      expect(credential.password).to.eq('some-password');
+      expect(credential._email).to.eq('some-email');
+      expect(credential._password).to.eq('some-password');
       expect(credential.providerId).to.eq(ProviderId.PASSWORD);
       expect(credential.signInMethod).to.eq(SignInMethod.EMAIL_PASSWORD);
     });
@@ -54,8 +54,8 @@ describe('core/providers/email', () => {
         'some-email',
         actionLink
       );
-      expect(credential.email).to.eq('some-email');
-      expect(credential.password).to.eq('CODE');
+      expect(credential._email).to.eq('some-email');
+      expect(credential._password).to.eq('CODE');
       expect(credential.providerId).to.eq(ProviderId.PASSWORD);
       expect(credential.signInMethod).to.eq(SignInMethod.EMAIL_LINK);
     });

packages-exp/auth-exp/src/core/providers/oauth.ts

@@ -128,6 +128,10 @@ export abstract class BaseOAuthProvider
  * @public
  */
 export class OAuthProvider extends BaseOAuthProvider {
+  /**
+   * Creates an {@link OAuthCredential} from a JSON string or a plain object.
+   * @param json A plain object or a JSON string
+   */
   static credentialFromJSON(json: object | string): OAuthCredential {
     const obj = typeof json === 'string' ? JSON.parse(json) : json;
     _assert(

packages-exp/auth-exp/src/core/providers/saml.ts

@@ -46,6 +46,22 @@ export class SAMLAuthProvider extends FederatedAuthProvider {
     super(providerId);
   }
 
+  /**
+   * Generates an {@link AuthCredential} from a {@link UserCredential} after a
+   * successful SAML flow completes.
+   *
+   * @remarks
+   *
+   * For example, to get an {@link AuthCredential}, you could write the
+   * following code:
+   *
+   * ```js
+   * const userCredential = await signInWithPopup(auth, samlProvider);
+   * const credential = SAMLAuthProvider.credentialFromResult(userCredential);
+   * ```
+   *
+   * @param userCredential
+   */
   static credentialFromResult(
     userCredential: UserCredential
   ): AuthCredential | null {
@@ -54,12 +70,22 @@ export class SAMLAuthProvider extends FederatedAuthProvider {
     );
   }
 
+  /**
+   * Used to extract the underlying {@link OAuthCredential} from a {@link AuthError} which was
+   * thrown during a sign-in, link, or reauthenticate operation.
+   *
+   * @param userCredential - The user credential.
+   */
   static credentialFromError(error: FirebaseError): AuthCredential | null {
     return SAMLAuthProvider.samlCredentialFromTaggedObject(
       (error.customData || {}) as TaggedWithTokenResponse
     );
   }
 
+  /**
+   * Creates an {@link AuthCredential} from a JSON string or a plain object.
+   * @param json A plain object or a JSON string
+   */
   static credentialFromJSON(json: string | object): AuthCredential {
     const credential = SAMLAuthCredential.fromJSON(json);
     _assert(credential, AuthErrorCode.ARGUMENT_ERROR);

packages-exp/auth-exp/src/core/providers/twitter.ts

@@ -85,7 +85,9 @@ import { BaseOAuthProvider } from './oauth';
  * @public
  */
 export class TwitterAuthProvider extends BaseOAuthProvider {
+  /** Always set to {@link SignInMethod.TWITTER}. */
   static readonly TWITTER_SIGN_IN_METHOD = SignInMethod.TWITTER;
+  /** Always set to {@link ProviderId.TWITTER}. */
   static readonly PROVIDER_ID = ProviderId.TWITTER;
 
   constructor() {

packages-exp/auth-exp/src/core/strategies/email_link.ts

@@ -155,7 +155,7 @@ export async function signInWithEmailLink(
   // Check if the tenant ID in the email link matches the tenant ID on Auth
   // instance.
   _assert(
-    credential.tenantId === (authModular.tenantId || null),
+    credential._tenantId === (authModular.tenantId || null),
     authModular,
     AuthErrorCode.TENANT_ID_MISMATCH
   );