Add documentation for auth@next (#3938)

* Add documentation for auth@next

* Update packages-exp/auth-types-exp/index.d.ts

Co-authored-by: Sam Horlbeck Olsen <[email protected]>

* Update packages-exp/auth-types-exp/index.d.ts

Co-authored-by: Sam Horlbeck Olsen <[email protected]>

* Update packages-exp/auth-types-exp/index.d.ts

Co-authored-by: Sam Horlbeck Olsen <[email protected]>

* Update packages-exp/auth-types-exp/index.d.ts

Co-authored-by: Sam Horlbeck Olsen <[email protected]>

* Update packages-exp/auth-types-exp/index.d.ts

Co-authored-by: Sam Horlbeck Olsen <[email protected]>

* Update packages-exp/auth-types-exp/index.d.ts

Co-authored-by: Sam Horlbeck Olsen <[email protected]>

* Update packages-exp/auth-types-exp/index.d.ts

Co-authored-by: Sam Horlbeck Olsen <[email protected]>

* Update packages-exp/auth-types-exp/index.d.ts

Co-authored-by: Sam Horlbeck Olsen <[email protected]>

* Update packages-exp/auth-types-exp/index.d.ts

Co-authored-by: Sam Horlbeck Olsen <[email protected]>

* Update packages-exp/auth-types-exp/index.d.ts

Co-authored-by: Sam Horlbeck Olsen <[email protected]>

* Update packages-exp/auth-types-exp/index.d.ts

Co-authored-by: Sam Horlbeck Olsen <[email protected]>

* Update packages-exp/auth-types-exp/index.d.ts

Co-authored-by: Sam Horlbeck Olsen <[email protected]>

* Update packages-exp/auth-types-exp/index.d.ts

Co-authored-by: Sam Horlbeck Olsen <[email protected]>

* PR Feedback

* More docs + PR feedback

* Fix typo and remove stray hyphen

* One more pass of feedback

Co-authored-by: Sam Horlbeck Olsen <[email protected]>

Author: avolkovi

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

@@ -4,6 +4,14 @@
 
 ## ActionCodeInfo.data property
 
+The data associated with the action code. For the [Operation.PASSWORD\_RESET](./auth-types.operation.password_reset.md)<!-- -->, [Operation.VERIFY\_EMAIL](./auth-types.operation.verify_email.md)<!-- -->, and [Operation.RECOVER\_EMAIL](./auth-types.operation.recover_email.md) actions, this object contains an email field with the address the email was sent to.
+
+For the [Operation.RECOVER\_EMAIL](./auth-types.operation.recover_email.md) action, which allows a user to undo an email address change, this object also contains a `previousEmail` field with the user account's current email address. After the action completes, the user's email address will revert to the value in the `email` field from the value in `previousEmail` field.
+
+For the [Operation.VERIFY\_AND\_CHANGE\_EMAIL](./auth-types.operation.verify_and_change_email.md) action, which allows a user to verify the email before updating it, this object contains a `previousEmail` field with the user account's email address before updating. After the action completes, the user's email address will be updated to the value in the `email` field from the value in `previousEmail` field.
+
+For the [Operation.REVERT\_SECOND\_FACTOR\_ADDITION](./auth-types.operation.revert_second_factor_addition.md) action, which allows a user to unenroll a newly added second factor, this object contains a `multiFactorInfo` field with the information about the second factor. For phone second factor, the `multiFactorInfo` is a [MultiFactorInfo](./auth-types.multifactorinfo.md) object, which contains the phone number.
+
 <b>Signature:</b>
 
 ```typescript

docs-exp/auth-types.actioncodeinfo.data.md

@@ -4,7 +4,7 @@
 
 ## ActionCodeInfo interface
 
-https://firebase.google.com/docs/reference/js/firebase.auth.ActionCodeInfo
+A response from `checkActionCode`<!-- -->.
 
 <b>Signature:</b>
 
@@ -16,6 +16,6 @@ export interface ActionCodeInfo
 
 |  Property | Type | Description |
 |  --- | --- | --- |
-|  [data](./auth-types.actioncodeinfo.data.md) | { email?: string \| null; multiFactorInfo?: [MultiFactorInfo](./auth-types.multifactorinfo.md) \| null; previousEmail?: string \| null; } |  |
-|  [operation](./auth-types.actioncodeinfo.operation.md) | [Operation](./auth-types.operation.md) |  |
+|  [data](./auth-types.actioncodeinfo.data.md) | { email?: string \| null; multiFactorInfo?: [MultiFactorInfo](./auth-types.multifactorinfo.md) \| null; previousEmail?: string \| null; } | The data associated with the action code. For the [Operation.PASSWORD\_RESET](./auth-types.operation.password_reset.md)<!-- -->, [Operation.VERIFY\_EMAIL](./auth-types.operation.verify_email.md)<!-- -->, and [Operation.RECOVER\_EMAIL](./auth-types.operation.recover_email.md) actions, this object contains an email field with the address the email was sent to.<!-- -->For the [Operation.RECOVER\_EMAIL](./auth-types.operation.recover_email.md) action, which allows a user to undo an email address change, this object also contains a <code>previousEmail</code> field with the user account's current email address. After the action completes, the user's email address will revert to the value in the <code>email</code> field from the value in <code>previousEmail</code> field.<!-- -->For the [Operation.VERIFY\_AND\_CHANGE\_EMAIL](./auth-types.operation.verify_and_change_email.md) action, which allows a user to verify the email before updating it, this object contains a <code>previousEmail</code> field with the user account's email address before updating. After the action completes, the user's email address will be updated to the value in the <code>email</code> field from the value in <code>previousEmail</code> field.<!-- -->For the [Operation.REVERT\_SECOND\_FACTOR\_ADDITION](./auth-types.operation.revert_second_factor_addition.md) action, which allows a user to unenroll a newly added second factor, this object contains a <code>multiFactorInfo</code> field with the information about the second factor. For phone second factor, the <code>multiFactorInfo</code> is a [MultiFactorInfo](./auth-types.multifactorinfo.md) object, which contains the phone number. |
+|  [operation](./auth-types.actioncodeinfo.operation.md) | [Operation](./auth-types.operation.md) | The type of operation that generated the action code. |
 

docs-exp/auth-types.actioncodeinfo.md

@@ -4,6 +4,8 @@
 
 ## ActionCodeInfo.operation property
 
+The type of operation that generated the action code.
+
 <b>Signature:</b>
 
 ```typescript

docs-exp/auth-types.actioncodeinfo.operation.md

@@ -4,6 +4,8 @@
 
 ## ActionCodeSettings.android property
 
+Sets the Android package name. This will try to open the link in an android app if it is installed. If `installApp` is passed, it specifies whether to install the Android app if the device supports it and the app is not already installed. If this field is provided without a `packageName`<!-- -->, an error is thrown explaining that the `packageName` must be provided in conjunction with this field. If `minimumVersion` is specified, and an older version of the app is installed, the user is taken to the Play Store to upgrade the app.
+
 <b>Signature:</b>
 
 ```typescript

docs-exp/auth-types.actioncodesettings.android.md

@@ -4,6 +4,8 @@
 
 ## ActionCodeSettings.dynamicLinkDomain property
 
+When multiple custom dynamic link domains are defined for a project, specify which one to use when the link is to be opened via a specified mobile app (for example, `example.page.link`<!-- -->). Otherwise the first domain is automatically selected.
+
 <b>Signature:</b>
 
 ```typescript

docs-exp/auth-types.actioncodesettings.dynamiclinkdomain.md

@@ -4,6 +4,8 @@
 
 ## ActionCodeSettings.handleCodeInApp property
 
+The default is false. When set to true, the action code link will be be sent as a Universal Link or Android App Link and will be opened by the app if installed. In the false case, the code will be sent to the web widget first and then on continue will redirect to the app if installed.
+
 <b>Signature:</b>
 
 ```typescript

docs-exp/auth-types.actioncodesettings.handlecodeinapp.md

@@ -4,6 +4,10 @@
 
 ## ActionCodeSettings.iOS property
 
+Sets the iOS bundle ID. This will try to open the link in an iOS app if it is installed.
+
+App installation is not supported for iOS.
+
 <b>Signature:</b>
 
 ```typescript

docs-exp/auth-types.actioncodesettings.ios.md

@@ -4,7 +4,7 @@
 
 ## ActionCodeSettings interface
 
-https://firebase.google.com/docs/reference/js/firebase.auth\#actioncodesettings
+This is the interface that defines the required continue/state URL with optional Android and iOS bundle identifiers.
 
 <b>Signature:</b>
 
@@ -16,9 +16,9 @@ export interface ActionCodeSettings
 
 |  Property | Type | Description |
 |  --- | --- | --- |
-|  [android](./auth-types.actioncodesettings.android.md) | { installApp?: boolean; minimumVersion?: string; packageName: string; } |  |
-|  [dynamicLinkDomain](./auth-types.actioncodesettings.dynamiclinkdomain.md) | string |  |
-|  [handleCodeInApp](./auth-types.actioncodesettings.handlecodeinapp.md) | boolean |  |
-|  [iOS](./auth-types.actioncodesettings.ios.md) | { bundleId: string; } |  |
-|  [url](./auth-types.actioncodesettings.url.md) | string |  |
+|  [android](./auth-types.actioncodesettings.android.md) | { installApp?: boolean; minimumVersion?: string; packageName: string; } | Sets the Android package name. This will try to open the link in an android app if it is installed. If <code>installApp</code> is passed, it specifies whether to install the Android app if the device supports it and the app is not already installed. If this field is provided without a <code>packageName</code>, an error is thrown explaining that the <code>packageName</code> must be provided in conjunction with this field. If <code>minimumVersion</code> is specified, and an older version of the app is installed, the user is taken to the Play Store to upgrade the app. |
+|  [dynamicLinkDomain](./auth-types.actioncodesettings.dynamiclinkdomain.md) | string | When multiple custom dynamic link domains are defined for a project, specify which one to use when the link is to be opened via a specified mobile app (for example, <code>example.page.link</code>). Otherwise the first domain is automatically selected. |
+|  [handleCodeInApp](./auth-types.actioncodesettings.handlecodeinapp.md) | boolean | The default is false. When set to true, the action code link will be be sent as a Universal Link or Android App Link and will be opened by the app if installed. In the false case, the code will be sent to the web widget first and then on continue will redirect to the app if installed. |
+|  [iOS](./auth-types.actioncodesettings.ios.md) | { bundleId: string; } | Sets the iOS bundle ID. This will try to open the link in an iOS app if it is installed.<!-- -->App installation is not supported for iOS. |
+|  [url](./auth-types.actioncodesettings.url.md) | string | Sets the link continue/state URL, which has different meanings in different contexts: - When the link is handled in the web action widgets, this is the deep link in the <code>continueUrl</code> query parameter. - When the link is handled in the app directly, this is the <code>continueUrl</code> query parameter in the deep link of the Dynamic Link. |
 

docs-exp/auth-types.actioncodesettings.md

@@ -4,6 +4,8 @@
 
 ## ActionCodeSettings.url property
 
+Sets the link continue/state URL, which has different meanings in different contexts: - When the link is handled in the web action widgets, this is the deep link in the `continueUrl` query parameter. - When the link is handled in the app directly, this is the `continueUrl` query parameter in the deep link of the Dynamic Link.
+
 <b>Signature:</b>
 
 ```typescript

docs-exp/auth-types.actioncodesettings.url.md

@@ -4,6 +4,8 @@
 
 ## AdditionalUserInfo.isNewUser property
 
+Whether the user is new (created via sign-up) or existing (authenticated using sign-in).
+
 <b>Signature:</b>
 
 ```typescript

docs-exp/auth-types.additionaluserinfo.isnewuser.md

@@ -4,7 +4,7 @@
 
 ## AdditionalUserInfo interface
 
-Additional user information.
+A structure containing additional user information from a federated identity provider.
 
 <b>Signature:</b>
 
@@ -16,8 +16,8 @@ export interface AdditionalUserInfo
 
 |  Property | Type | Description |
 |  --- | --- | --- |
-|  [isNewUser](./auth-types.additionaluserinfo.isnewuser.md) | boolean |  |
-|  [profile](./auth-types.additionaluserinfo.profile.md) | [UserProfile](./auth-types.userprofile.md) \| null |  |
-|  [providerId](./auth-types.additionaluserinfo.providerid.md) | [ProviderId](./auth-types.providerid.md) \| null |  |
-|  [username](./auth-types.additionaluserinfo.username.md) | string \| null |  |
+|  [isNewUser](./auth-types.additionaluserinfo.isnewuser.md) | boolean | Whether the user is new (created via sign-up) or existing (authenticated using sign-in). |
+|  [profile](./auth-types.additionaluserinfo.profile.md) | [UserProfile](./auth-types.userprofile.md) \| null | Map containing IDP-specific user data. |
+|  [providerId](./auth-types.additionaluserinfo.providerid.md) | [ProviderId](./auth-types.providerid.md) \| null | Identifier for the provider used to authenticate this user. |
+|  [username](./auth-types.additionaluserinfo.username.md) | string \| null | The username if the provider is GitHub or Twitter. |
 

docs-exp/auth-types.additionaluserinfo.md

@@ -4,6 +4,8 @@
 
 ## AdditionalUserInfo.profile property
 
+Map containing IDP-specific user data.
+
 <b>Signature:</b>
 
 ```typescript

docs-exp/auth-types.additionaluserinfo.profile.md

@@ -4,6 +4,8 @@
 
 ## AdditionalUserInfo.providerId property
 
+Identifier for the provider used to authenticate this user.
+
 <b>Signature:</b>
 
 ```typescript

docs-exp/auth-types.additionaluserinfo.providerid.md

@@ -4,6 +4,8 @@
 
 ## AdditionalUserInfo.username property
 
+The username if the provider is GitHub or Twitter.
+
 <b>Signature:</b>
 
 ```typescript

docs-exp/auth-types.additionaluserinfo.username.md

@@ -4,7 +4,7 @@
 
 ## ApplicationVerifier interface
 
-https://firebase.google.com/docs/reference/js/firebase.auth.ApplicationVerifier
+A verifier for domain verification and abuse prevention. Currently, the only implementation is [RecaptchaVerifier](./auth-types.recaptchaverifier.md)<!-- -->.
 
 <b>Signature:</b>
 
@@ -16,11 +16,11 @@ export interface ApplicationVerifier
 
 |  Property | Type | Description |
 |  --- | --- | --- |
-|  [type](./auth-types.applicationverifier.type.md) | string |  |
+|  [type](./auth-types.applicationverifier.type.md) | string | Identifies the type of application verifier (e.g. "recaptcha"). |
 
 ## Methods
 
 |  Method | Description |
 |  --- | --- |
-|  [verify()](./auth-types.applicationverifier.verify.md) |  |
+|  [verify()](./auth-types.applicationverifier.verify.md) | Executes the verification process. |
 

docs-exp/auth-types.applicationverifier.md

@@ -4,6 +4,8 @@
 
 ## ApplicationVerifier.type property
 
+Identifies the type of application verifier (e.g. "recaptcha").
+
 <b>Signature:</b>
 
 ```typescript

docs-exp/auth-types.applicationverifier.type.md

@@ -4,6 +4,8 @@
 
 ## ApplicationVerifier.verify() method
 
+Executes the verification process.
+
 <b>Signature:</b>
 
 ```typescript
@@ -13,3 +15,5 @@ verify(): Promise<string>;
 
 Promise&lt;string&gt;
 
+A Promise for a token that can be used to assert the validity of a request.
+

docs-exp/auth-types.applicationverifier.verify.md

@@ -4,6 +4,8 @@
 
 ## Auth.config property
 
+The [Config](./auth-types.config.md) used to initialize this instance.
+
 <b>Signature:</b>
 
 ```typescript

docs-exp/auth-types.auth.config.md

@@ -4,6 +4,8 @@
 
 ## Auth.currentUser property
 
+The currently signed-in user (or null).
+
 <b>Signature:</b>
 
 ```typescript

docs-exp/auth-types.auth.currentuser.md

@@ -4,6 +4,8 @@
 
 ## Auth.languageCode property
 
+The Auth instance's language code. This is a readable/writable property. When set to null, the default Firebase Console language setting is applied. The language code will propagate to email action templates (password reset, email verification and email change revocation), SMS templates for phone authentication, reCAPTCHA verifier and OAuth popup/redirect operations provided the specified providers support localization with the language code specified.
+
 <b>Signature:</b>
 
 ```typescript

docs-exp/auth-types.auth.languagecode.md

@@ -4,7 +4,9 @@
 
 ## Auth interface
 
-https://firebase.google.com/docs/reference/js/firebase.auth.Auth
+The Firebase Auth service interface.
+
+See [Firebase Authentication](https://firebase.google.com/docs/auth/) for a full guide on how to use the Firebase Auth service.
 
 <b>Signature:</b>
 
@@ -16,22 +18,22 @@ export interface Auth
 
 |  Property | Type | Description |
 |  --- | --- | --- |
-|  [config](./auth-types.auth.config.md) | [Config](./auth-types.config.md) |  |
-|  [currentUser](./auth-types.auth.currentuser.md) | [User](./auth-types.user.md) \| null |  |
-|  [languageCode](./auth-types.auth.languagecode.md) | string \| null |  |
-|  [name](./auth-types.auth.name.md) | string |  |
-|  [settings](./auth-types.auth.settings.md) | [AuthSettings](./auth-types.authsettings.md) |  |
-|  [tenantId](./auth-types.auth.tenantid.md) | string \| null |  |
+|  [config](./auth-types.auth.config.md) | [Config](./auth-types.config.md) | The [Config](./auth-types.config.md) used to initialize this instance. |
+|  [currentUser](./auth-types.auth.currentuser.md) | [User](./auth-types.user.md) \| null | The currently signed-in user (or null). |
+|  [languageCode](./auth-types.auth.languagecode.md) | string \| null | The Auth instance's language code. This is a readable/writable property. When set to null, the default Firebase Console language setting is applied. The language code will propagate to email action templates (password reset, email verification and email change revocation), SMS templates for phone authentication, reCAPTCHA verifier and OAuth popup/redirect operations provided the specified providers support localization with the language code specified. |
+|  [name](./auth-types.auth.name.md) | string | The name of the app associated with the Auth service instance. |
+|  [settings](./auth-types.auth.settings.md) | [AuthSettings](./auth-types.authsettings.md) | The Auth instance's settings. This is used to edit/read configuration related options like app verification mode for phone authentication. |
+|  [tenantId](./auth-types.auth.tenantid.md) | string \| null | The Auth instance's tenant ID. This is a readable/writable property. When you set the tenant ID of an Auth instance, all future sign-in/sign-up operations will pass this tenant ID and sign in or sign up users to the specified tenant project. When set to null, users are signed in to the parent project. By default, this is set to null. |
 
 ## Methods
 
 |  Method | Description |
 |  --- | --- |
-|  [onAuthStateChanged(nextOrObserver, error, completed)](./auth-types.auth.onauthstatechanged.md) |  |
-|  [onIdTokenChanged(nextOrObserver, error, completed)](./auth-types.auth.onidtokenchanged.md) |  |
-|  [setPersistence(persistence)](./auth-types.auth.setpersistence.md) |  |
-|  [signOut()](./auth-types.auth.signout.md) |  |
-|  [updateCurrentUser(user)](./auth-types.auth.updatecurrentuser.md) |  |
-|  [useDeviceLanguage()](./auth-types.auth.usedevicelanguage.md) |  |
-|  [useEmulator(url)](./auth-types.auth.useemulator.md) |  |
+|  [onAuthStateChanged(nextOrObserver, error, completed)](./auth-types.auth.onauthstatechanged.md) | Adds an observer for changes to the user's sign-in state.<!-- -->To keep the old behavior, see [Auth.onIdTokenChanged()](./auth-types.auth.onidtokenchanged.md)<!-- -->. |
+|  [onIdTokenChanged(nextOrObserver, error, completed)](./auth-types.auth.onidtokenchanged.md) | Adds an observer for changes to the signed-in user's ID token, which includes sign-in, sign-out, and token refresh events. |
+|  [setPersistence(persistence)](./auth-types.auth.setpersistence.md) | Changes the type of persistence on the Auth instance for the currently saved Auth session and applies this type of persistence for future sign-in requests, including sign-in with redirect requests.<!-- -->This makes it easy for a user signing in to specify whether their session should be remembered or not. It also makes it easier to never persist the Auth state for applications that are shared by other users or have sensitive data. |
+|  [signOut()](./auth-types.auth.signout.md) | Signs out the current user. |
+|  [updateCurrentUser(user)](./auth-types.auth.updatecurrentuser.md) | Asynchronously sets the provided user as <code>currentUser</code> on the Auth instance. A new instance copy of the user provided will be made and set as currentUser.<!-- -->This will trigger [Auth.onAuthStateChanged()](./auth-types.auth.onauthstatechanged.md) and [Auth.onIdTokenChanged()](./auth-types.auth.onidtokenchanged.md) listeners like other sign in methods.<!-- -->The operation fails with an error if the user to be updated belongs to a different Firebase project. |
+|  [useDeviceLanguage()](./auth-types.auth.usedevicelanguage.md) | Sets the current language to the default device/browser preference. |
+|  [useEmulator(url)](./auth-types.auth.useemulator.md) | Modify this Auth instance to communicate with the Firebase Auth emulator. This must be called synchronously immediately following the first call to <code>initializeAuth()</code>. Do not use with production credentials as emulator traffic is not encrypted. |
 

docs-exp/auth-types.auth.md

@@ -4,6 +4,8 @@
 
 ## Auth.name property
 
+The name of the app associated with the Auth service instance.
+
 <b>Signature:</b>
 
 ```typescript

docs-exp/auth-types.auth.name.md

@@ -4,6 +4,10 @@
 
 ## Auth.onAuthStateChanged() method
 
+Adds an observer for changes to the user's sign-in state.
+
+To keep the old behavior, see [Auth.onIdTokenChanged()](./auth-types.auth.onidtokenchanged.md)<!-- -->.
+
 <b>Signature:</b>
 
 ```typescript
@@ -18,9 +22,9 @@ onAuthStateChanged(
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  nextOrObserver | [NextOrObserver](./auth-types.nextorobserver.md)<!-- -->&lt;[User](./auth-types.user.md)<!-- -->&gt; |  |
-|  error | ErrorFn |  |
-|  completed | CompleteFn |  |
+|  nextOrObserver | [NextOrObserver](./auth-types.nextorobserver.md)<!-- -->&lt;[User](./auth-types.user.md)<!-- -->&gt; | callback triggered on change. |
+|  error | ErrorFn | callback triggered on error. |
+|  completed | CompleteFn | callback triggered when observer is removed. |
 
 <b>Returns:</b>