Add documentation for @firebase/auth-exp (#3952)

* Add documentation for @firebase/auth-exp

* PR Feedback

* Update examples to account for change in API related to credentialFromResult

* Rebase conflicts

Author: avolkovi

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

@@ -97,7 +97,7 @@ export abstract class AuthCredential {
   toJSON(): object;
 }
 
-// @public (undocumented)
+// @public
 export interface AuthError extends FirebaseError {
   readonly appName: string;
   readonly email?: string;
@@ -247,7 +247,10 @@ export interface Persistence {
 
 // @public
 export abstract class PhoneAuthCredential extends AuthCredential {
+  // (undocumented)
   static fromJSON(json: object | string): PhoneAuthCredential | null;
+  // (undocumented)
+  toJSON(): object;
 }
 
 // @public

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

@@ -4,13 +4,7 @@
 
 ## 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.
+The data associated with the action code.
 
 <b>Signature:</b>
 
@@ -21,3 +15,14 @@ data: {
     previousEmail?: string | null;
   };
 ```
+
+## Remarks
+
+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.
+

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

@@ -4,7 +4,7 @@
 
 ## ActionCodeInfo interface
 
-A response from `checkActionCode`<!-- -->.
+A response from [checkActionCode()](./auth.checkactioncode.md)<!-- -->.
 
 <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; } | 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. |
+|  [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. |
 |  [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,7 +4,7 @@
 
 ## 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.
+Sets the Android package name.
 
 <b>Signature:</b>
 
@@ -15,3 +15,8 @@ android?: {
     packageName: string;
   };
 ```
+
+## Remarks
+
+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.
+

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

@@ -4,7 +4,7 @@
 
 ## 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.
+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`<!-- -->).
 
 <b>Signature:</b>
 

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

@@ -4,10 +4,15 @@
 
 ## 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.
+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.
 
 <b>Signature:</b>
 
 ```typescript
 handleCodeInApp?: boolean;
 ```
+
+## Remarks
+
+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.
+

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

@@ -4,9 +4,7 @@
 
 ## 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.
+Sets the iOS bundle ID.
 
 <b>Signature:</b>
 
@@ -15,3 +13,10 @@ iOS?: {
     bundleId: string;
   };
 ```
+
+## Remarks
+
+This will try to open the link in an iOS app if it is installed.
+
+App installation is not supported for iOS.
+

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

@@ -4,7 +4,7 @@
 
 ## ActionCodeSettings interface
 
-This is the interface that defines the required continue/state URL with optional Android and iOS bundle identifiers.
+An 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; } | 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. |
+|  [android](./auth-types.actioncodesettings.android.md) | { installApp?: boolean; minimumVersion?: string; packageName: string; } | Sets the Android package name. |
+|  [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>). |
+|  [handleCodeInApp](./auth-types.actioncodesettings.handlecodeinapp.md) | boolean | 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. |
+|  [iOS](./auth-types.actioncodesettings.ios.md) | { bundleId: string; } | Sets the iOS bundle ID. |
+|  [url](./auth-types.actioncodesettings.url.md) | string | Sets the link continue/state URL. |
 

docs-exp/auth-types.actioncodesettings.md

@@ -4,10 +4,15 @@
 
 ## 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.
+Sets the link continue/state URL.
 
 <b>Signature:</b>
 
 ```typescript
 url: string;
 ```
+
+## Remarks
+
+This 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.
+

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

@@ -27,5 +27,5 @@ export abstract class ActionCodeURL
 
 |  Method | Modifiers | Description |
 |  --- | --- | --- |
-|  [parseLink(link)](./auth-types.actioncodeurl.parselink.md) | <code>static</code> | Parses the email action link string and returns an ActionCodeURL object if the link is valid, otherwise returns null. |
+|  [parseLink(link)](./auth-types.actioncodeurl.parselink.md) | <code>static</code> | Parses the email action link string and returns an [ActionCodeURL](./auth-types.actioncodeurl.md) if the link is valid, otherwise returns null. |
 

docs-exp/auth-types.actioncodeurl.md

@@ -4,7 +4,7 @@
 
 ## ActionCodeURL.parseLink() method
 
-Parses the email action link string and returns an ActionCodeURL object if the link is valid, otherwise returns null.
+Parses the email action link string and returns an [ActionCodeURL](./auth-types.actioncodeurl.md) if the link is valid, otherwise returns null.
 
 <b>Signature:</b>
 

docs-exp/auth-types.actioncodeurl.parselink.md

@@ -4,14 +4,18 @@
 
 ## ApplicationVerifier interface
 
-A verifier for domain verification and abuse prevention. Currently, the only implementation is [RecaptchaVerifier](./auth-types.recaptchaverifier.md)<!-- -->.
+A verifier for domain verification and abuse prevention.
 
 <b>Signature:</b>
 
 ```typescript
 export interface ApplicationVerifier 
 ```
 
+## Remarks
+
+Currently, the only implementation is [RecaptchaVerifier](./auth.recaptchaverifier.md)<!-- -->.
+
 ## Properties
 
 |  Property | Type | Description |

docs-exp/auth-types.applicationverifier.md

@@ -4,10 +4,15 @@
 
 ## 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.
+The Auth instance's language code.
 
 <b>Signature:</b>
 
 ```typescript
 languageCode: string | null;
 ```
+
+## Remarks
+
+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.
+