diff --git a/common/api-review/auth-exp.api.md b/common/api-review/auth-exp.api.md index e5d78616b0b..dd101d24fb7 100644 --- a/common/api-review/auth-exp.api.md +++ b/common/api-review/auth-exp.api.md @@ -101,14 +101,14 @@ export class AuthCredential { protected constructor( providerId: string, signInMethod: string); - // Warning: (ae-forgotten-export) The symbol "AuthInternal" needs to be exported by the entry point index.d.ts - // Warning: (ae-forgotten-export) The symbol "PhoneOrOauthTokenResponse" needs to be exported by the entry point index.d.ts + // Warning: (ae-forgotten-export) The symbol "AuthInternal" needs to be exported by the entry point index.doc.d.ts + // Warning: (ae-forgotten-export) The symbol "PhoneOrOauthTokenResponse" needs to be exported by the entry point index.doc.d.ts // // @internal (undocumented) _getIdTokenResponse(_auth: AuthInternal): Promise; // @internal (undocumented) _getReauthenticationResolver(_auth: AuthInternal): Promise; - // Warning: (ae-forgotten-export) The symbol "IdTokenResponse" needs to be exported by the entry point index.d.ts + // Warning: (ae-forgotten-export) The symbol "IdTokenResponse" needs to be exported by the entry point index.doc.d.ts // // @internal (undocumented) _linkToIdToken(_auth: AuthInternal, _idToken: string): Promise; @@ -276,6 +276,9 @@ export function connectAuthEmulator(auth: Auth, url: string, options?: { disableWarnings: boolean; }): void; +// @public +export const cordovaPopupRedirectResolver: PopupRedirectResolver; + // @public export function createUserWithEmailAndPassword(auth: Auth, email: string, password: string): Promise; @@ -339,7 +342,7 @@ export interface EmulatorConfig { export { ErrorFn } -// Warning: (ae-forgotten-export) The symbol "BaseOAuthProvider" needs to be exported by the entry point index.d.ts +// Warning: (ae-forgotten-export) The symbol "BaseOAuthProvider" needs to be exported by the entry point index.doc.d.ts // // @public export class FacebookAuthProvider extends BaseOAuthProvider { @@ -481,7 +484,7 @@ export type NextOrObserver = NextFn | Observer; export class OAuthCredential extends AuthCredential { accessToken?: string; static fromJSON(json: string | object): OAuthCredential | null; - // Warning: (ae-forgotten-export) The symbol "OAuthCredentialParams" needs to be exported by the entry point index.d.ts + // Warning: (ae-forgotten-export) The symbol "OAuthCredentialParams" needs to be exported by the entry point index.doc.d.ts // // @internal (undocumented) static _fromParams(params: OAuthCredentialParams): OAuthCredential; @@ -560,7 +563,7 @@ export class PhoneAuthCredential extends AuthCredential { _getReauthenticationResolver(auth: AuthInternal): Promise; // @internal (undocumented) _linkToIdToken(auth: AuthInternal, idToken: string): Promise; - // Warning: (ae-forgotten-export) The symbol "SignInWithPhoneNumberRequest" needs to be exported by the entry point index.d.ts + // Warning: (ae-forgotten-export) The symbol "SignInWithPhoneNumberRequest" needs to be exported by the entry point index.doc.d.ts // // @internal (undocumented) _makeVerificationRequest(): SignInWithPhoneNumberRequest; @@ -633,6 +636,9 @@ export interface ReactNativeAsyncStorage { setItem(key: string, value: string): Promise; } +// @public +export const reactNativeLocalPersistence: Persistence; + // @public export function reauthenticateWithCredential(user: User, credential: AuthCredential): Promise; @@ -651,13 +657,13 @@ export interface RecaptchaParameters { [key: string]: any; } -// Warning: (ae-forgotten-export) The symbol "ApplicationVerifierInternal" needs to be exported by the entry point index.d.ts +// Warning: (ae-forgotten-export) The symbol "ApplicationVerifierInternal" needs to be exported by the entry point index.doc.d.ts // // @public export class RecaptchaVerifier implements ApplicationVerifierInternal { constructor(containerOrId: HTMLElement | string, parameters: RecaptchaParameters, authExtern: Auth); clear(): void; - // Warning: (ae-forgotten-export) The symbol "ReCaptchaLoader" needs to be exported by the entry point index.d.ts + // Warning: (ae-forgotten-export) The symbol "ReCaptchaLoader" needs to be exported by the entry point index.doc.d.ts // // @internal (undocumented) readonly _recaptchaLoader: ReCaptchaLoader; @@ -671,7 +677,7 @@ export class RecaptchaVerifier implements ApplicationVerifierInternal { // @public export function reload(user: User): Promise; -// Warning: (ae-forgotten-export) The symbol "FederatedAuthProvider" needs to be exported by the entry point index.d.ts +// Warning: (ae-forgotten-export) The symbol "FederatedAuthProvider" needs to be exported by the entry point index.doc.d.ts // // @public export class SAMLAuthProvider extends FederatedAuthProvider { @@ -815,4 +821,6 @@ export function verifyBeforeUpdateEmail(user: User, newEmail: string, actionCode export function verifyPasswordResetCode(auth: Auth, code: string): Promise; +// (No @packageDocumentation comment for this package) + ``` diff --git a/packages-exp/analytics-exp/src/api.ts b/packages-exp/analytics-exp/src/api.ts index 99fe14b2dfe..38fde73f535 100644 --- a/packages-exp/analytics-exp/src/api.ts +++ b/packages-exp/analytics-exp/src/api.ts @@ -60,11 +60,11 @@ declare module '@firebase/component' { } /** - * Returns a Firebase Analytics instance for the given app. + * Returns an {@link Analytics} instance for the given app. * * @public * - * @param app - The FirebaseApp to use. + * @param app - The {@link @firebase/app#FirebaseApp} to use. */ export function getAnalytics(app: FirebaseApp = getApp()): Analytics { app = getModularInstance(app); @@ -82,11 +82,11 @@ export function getAnalytics(app: FirebaseApp = getApp()): Analytics { } /** - * Returns a Firebase Analytics instance for the given app. + * Returns an {@link Analytics} instance for the given app. * * @public * - * @param app - The FirebaseApp to use. + * @param app - The {@link @firebase/app#FirebaseApp} to use. */ export function initializeAnalytics( app: FirebaseApp, @@ -115,7 +115,7 @@ export function initializeAnalytics( * 1. Check if it's not a browser extension environment. * 2. Check if cookies are enabled in current browser. * 3. Check if IndexedDB is supported by the browser environment. - * 4. Check if the current browser context is valid for using IndexedDB.open(). + * 4. Check if the current browser context is valid for using `IndexedDB.open()`. * * @public * @@ -140,11 +140,11 @@ export async function isSupported(): Promise { } /** - * Use gtag 'config' command to set 'screen_name'. + * Use gtag `config` command to set `screen_name`. * * @public * - * @param analyticsInstance - Firebase Analytics instance. + * @param analyticsInstance - The {@link Analytics} instance. * @param screenName - Screen name to set. */ export function setCurrentScreen( @@ -162,11 +162,11 @@ export function setCurrentScreen( } /** - * Use gtag 'config' command to set 'user_id'. + * Use gtag `config` command to set `user_id`. * * @public * - * @param analyticsInstance - Firebase Analytics instance. + * @param analyticsInstance - The {@link Analytics} instance. * @param id - User ID to set. */ export function setUserId( @@ -184,7 +184,7 @@ export function setUserId( } /** - * Use gtag 'config' command to set all params specified. + * Use gtag `config` command to set all params specified. * * @public */ @@ -203,12 +203,12 @@ export function setUserProperties( } /** - * Sets whether analytics collection is enabled for this app on this device. - * window['ga-disable-analyticsId'] = true; + * Sets whether Google Analytics collection is enabled for this app on this device. + * Sets global `window['ga-disable-analyticsId'] = true;` * * @public * - * @param analyticsInstance - Firebase Analytics instance. + * @param analyticsInstance - The {@link Analytics} instance. * @param enabled - If true, enables collection, if false, disables it. */ export function setAnalyticsCollectionEnabled( @@ -222,7 +222,7 @@ export function setAnalyticsCollectionEnabled( ).catch(e => logger.error(e)); } /** - * Sends analytics event with given `eventParams`. This method + * Sends a Google Analytics event with given `eventParams`. This method * automatically associates this logged event with this Firebase web * app instance on this device. * @public @@ -245,7 +245,7 @@ export function logEvent( ): void; /** - * Sends analytics event with given `eventParams`. This method + * Sends a Google Analytics event with given `eventParams`. This method * automatically associates this logged event with this Firebase web * app instance on this device. * @public @@ -268,7 +268,7 @@ export function logEvent( ): void; /** - * Sends analytics event with given `eventParams`. This method + * Sends a Google Analytics event with given `eventParams`. This method * automatically associates this logged event with this Firebase web * app instance on this device. * @public @@ -289,7 +289,7 @@ export function logEvent( ): void; /** - * Sends analytics event with given `eventParams`. This method + * Sends a Google Analytics event with given `eventParams`. This method * automatically associates this logged event with this Firebase web * app instance on this device. * @public @@ -311,7 +311,7 @@ export function logEvent( ): void; /** - * Sends analytics event with given `eventParams`. This method + * Sends a Google Analytics event with given `eventParams`. This method * automatically associates this logged event with this Firebase web * app instance on this device. * @public @@ -335,7 +335,7 @@ export function logEvent( ): void; /** - * Sends analytics event with given `eventParams`. This method + * Sends a Google Analytics event with given `eventParams`. This method * automatically associates this logged event with this Firebase web * app instance on this device. * @public @@ -355,7 +355,7 @@ export function logEvent( ): void; /** - * Sends analytics event with given `eventParams`. This method + * Sends a Google Analytics event with given `eventParams`. This method * automatically associates this logged event with this Firebase web * app instance on this device. * @public @@ -375,7 +375,7 @@ export function logEvent( ): void; /** - * Sends analytics event with given `eventParams`. This method + * Sends a Google Analytics event with given `eventParams`. This method * automatically associates this logged event with this Firebase web * app instance on this device. * @public @@ -394,7 +394,7 @@ export function logEvent( ): void; /** - * Sends analytics event with given `eventParams`. This method + * Sends a Google Analytics event with given `eventParams`. This method * automatically associates this logged event with this Firebase web * app instance on this device. * @public @@ -415,7 +415,7 @@ export function logEvent( ): void; /** - * Sends analytics event with given `eventParams`. This method + * Sends a Google Analytics event with given `eventParams`. This method * automatically associates this logged event with this Firebase web * app instance on this device. * @public @@ -441,7 +441,7 @@ export function logEvent( ): void; /** - * Sends analytics event with given `eventParams`. This method + * Sends a Google Analytics event with given `eventParams`. This method * automatically associates this logged event with this Firebase web * app instance on this device. * @public @@ -460,7 +460,7 @@ export function logEvent( ): void; /** - * Sends analytics event with given `eventParams`. This method + * Sends a Google Analytics event with given `eventParams`. This method * automatically associates this logged event with this Firebase web * app instance on this device. * @public @@ -479,7 +479,7 @@ export function logEvent( ): void; /** - * Sends analytics event with given `eventParams`. This method + * Sends a Google Analytics event with given `eventParams`. This method * automatically associates this logged event with this Firebase web * app instance on this device. * @public @@ -499,7 +499,7 @@ export function logEvent( ): void; /** - * Sends analytics event with given `eventParams`. This method + * Sends a Google Analytics event with given `eventParams`. This method * automatically associates this logged event with this Firebase web * app instance on this device. * @public @@ -520,7 +520,7 @@ export function logEvent( ): void; /** - * Sends analytics event with given `eventParams`. This method + * Sends a Google Analytics event with given `eventParams`. This method * automatically associates this logged event with this Firebase web * app instance on this device. * @public @@ -541,7 +541,7 @@ export function logEvent( ): void; /** - * Sends analytics event with given `eventParams`. This method + * Sends a Google Analytics event with given `eventParams`. This method * automatically associates this logged event with this Firebase web * app instance on this device. * @public @@ -561,7 +561,7 @@ export function logEvent( ): void; /** - * Sends analytics event with given `eventParams`. This method + * Sends a Google Analytics event with given `eventParams`. This method * automatically associates this logged event with this Firebase web * app instance on this device. * @public @@ -582,7 +582,7 @@ export function logEvent( ): void; /** - * Sends analytics event with given `eventParams`. This method + * Sends a Google Analytics event with given `eventParams`. This method * automatically associates this logged event with this Firebase web * app instance on this device. * @public @@ -601,7 +601,7 @@ export function logEvent( ): void; /** - * Sends analytics event with given `eventParams`. This method + * Sends a Google Analytics event with given `eventParams`. This method * automatically associates this logged event with this Firebase web * app instance on this device. * @public @@ -623,7 +623,7 @@ export function logEvent( ): void; /** - * Sends analytics event with given `eventParams`. This method + * Sends a Google Analytics event with given `eventParams`. This method * automatically associates this logged event with this Firebase web * app instance on this device. * @public @@ -644,7 +644,7 @@ export function logEvent( ): void; /** - * Sends analytics event with given `eventParams`. This method + * Sends a Google Analytics event with given `eventParams`. This method * automatically associates this logged event with this Firebase web * app instance on this device. * @public @@ -665,7 +665,7 @@ export function logEvent( ): void; /** - * Sends analytics event with given `eventParams`. This method + * Sends a Google Analytics event with given `eventParams`. This method * automatically associates this logged event with this Firebase web * app instance on this device. * @public @@ -681,7 +681,7 @@ export function logEvent( ): void; /** - * Sends analytics event with given `eventParams`. This method + * Sends a Google Analytics event with given `eventParams`. This method * automatically associates this logged event with this Firebase web * app instance on this device. * List of official event parameters can be found in the gtag.js diff --git a/packages-exp/analytics-exp/src/public-types.ts b/packages-exp/analytics-exp/src/public-types.ts index 2ad49e08350..4654428444b 100644 --- a/packages-exp/analytics-exp/src/public-types.ts +++ b/packages-exp/analytics-exp/src/public-types.ts @@ -18,8 +18,8 @@ import { FirebaseApp } from '@firebase/app-exp'; /** - * A set of common Analytics config settings recognized by - * gtag. + * A set of common Google Analytics config settings recognized by + * `gtag.js`. * @public */ export interface GtagConfigParams { @@ -67,12 +67,12 @@ export interface GtagConfigParams { */ 'cookie_flags'?: string; /** - * If set to false, disables all advertising features with gtag.js. + * If set to false, disables all advertising features with `gtag.js`. * See {@link https://developers.google.com/analytics/devguides/collection/ga4/display-features | Disable advertising features } */ 'allow_google_signals?': boolean; /** - * If set to false, disables all advertising personalization with gtag.js. + * If set to false, disables all advertising personalization with `gtag.js`. * See {@link https://developers.google.com/analytics/devguides/collection/ga4/display-features | Disable advertising features } */ 'allow_ad_personalization_signals'?: boolean; @@ -80,25 +80,26 @@ export interface GtagConfigParams { } /** - * Analytics initialization options. + * {@link Analytics} instance initialization options. * @public */ export interface AnalyticsSettings { /** - * Params to be passed in the initial gtag config call during analytics initialization. + * Params to be passed in the initial `gtag` config call during Firebase + * Analytics initialization. */ config?: GtagConfigParams | EventParams; } /** - * Additional options that can be passed to Firebase Analytics method + * Additional options that can be passed to Analytics method * calls such as `logEvent`, `setCurrentScreen`, etc. * @public */ export interface AnalyticsCallOptions { /** * If true, this config or event call applies globally to all - * analytics properties on the page. + * Google Analytics properties on the page. */ global: boolean; } @@ -109,7 +110,7 @@ export interface AnalyticsCallOptions { */ export interface Analytics { /** - * The FirebaseApp this Analytics instance is associated with. + * The {@link @firebase/app#FirebaseApp} this {@link Analytics} instance is associated with. */ app: FirebaseApp; } @@ -122,12 +123,12 @@ export interface Analytics { export interface SettingsOptions { /** Sets custom name for `gtag` function. */ gtagName?: string; - /** Sets custom name for `dataLayer` array used by gtag. */ + /** Sets custom name for `dataLayer` array used by `gtag.js`. */ dataLayerName?: string; } /** - * Any custom params the user may pass to gtag.js. + * Any custom params the user may pass to `gtag`. * @public */ export interface CustomParams { @@ -135,7 +136,7 @@ export interface CustomParams { } /** - * Type for standard gtag.js event names. `logEvent` also accepts any + * Type for standard Google Analytics event names. `logEvent` also accepts any * custom string and interprets it as a custom event name. * @public */ @@ -169,14 +170,14 @@ export type EventNameString = | 'view_search_results'; /** - * Standard analytics currency type. + * Standard Google Analytics currency type. * @public */ export type Currency = string | number; /* eslint-disable camelcase */ /** - * Standard analytics `Item` type. + * Standard Google Analytics `Item` type. * @public */ export interface Item { @@ -213,8 +214,8 @@ export interface Item { } /** - * Field previously used by some Analytics events. - * @deprecated Use Item instead. + * Field previously used by some Google Analytics events. + * @deprecated Use `Item` instead. * @public */ export interface Promotion { @@ -225,7 +226,7 @@ export interface Promotion { } /** - * Standard gtag.js control parameters. + * Standard `gtag.js` control parameters. * For more information, see * {@link https://developers.google.com/gtagjs/reference/ga4-events * | the GA4 reference documentation}. @@ -239,7 +240,7 @@ export interface ControlParams { } /** - * Standard gtag.js event parameters. + * Standard `gtag.js` event parameters. * For more information, see * {@link https://developers.google.com/gtagjs/reference/ga4-events * | the GA4 reference documentation}. diff --git a/packages-exp/app-check-exp/src/api.ts b/packages-exp/app-check-exp/src/api.ts index 4610f5a428b..fefe64519f3 100644 --- a/packages-exp/app-check-exp/src/api.ts +++ b/packages-exp/app-check-exp/src/api.ts @@ -46,7 +46,7 @@ export { ReCaptchaV3Provider, CustomProvider } from './providers'; /** * Activate App Check for the given app. Can be called only once per app. - * @param app - the FirebaseApp to activate App Check for + * @param app - the {@link @firebase/app#FirebaseApp} to activate App Check for * @param options - App Check initialization options * @public */ @@ -211,7 +211,7 @@ export function onTokenChanged( onCompletion?: () => void ): Unsubscribe; /** - * Wraps addTokenListener/removeTokenListener methods in an Observer + * Wraps `addTokenListener`/`removeTokenListener` methods in an `Observer` * pattern for public use. */ export function onTokenChanged( diff --git a/packages-exp/app-check-exp/src/public-types.ts b/packages-exp/app-check-exp/src/public-types.ts index a616fef07ba..cd735951ff5 100644 --- a/packages-exp/app-check-exp/src/public-types.ts +++ b/packages-exp/app-check-exp/src/public-types.ts @@ -26,7 +26,7 @@ export { Unsubscribe, PartialObserver } from '@firebase/util'; */ export interface AppCheck { /** - * The `FirebaseApp` this `AppCheck` instance is associated with. + * The {@link @firebase/app#FirebaseApp} this `AppCheck` instance is associated with. */ app: FirebaseApp; } diff --git a/packages-exp/app-exp/src/api.ts b/packages-exp/app-exp/src/api.ts index 79f2cbf3fee..7368a1671fe 100644 --- a/packages-exp/app-exp/src/api.ts +++ b/packages-exp/app-exp/src/api.ts @@ -49,7 +49,7 @@ import { deepEqual } from '@firebase/util'; export const SDK_VERSION = version; /** - * Creates and initializes a FirebaseApp instance. + * Creates and initializes a {@link @firebase/app#FirebaseApp} instance. * * See * {@link @@ -156,7 +156,7 @@ export function initializeApp( } /** - * Retrieves a FirebaseApp instance. + * Retrieves a {@link @firebase/app#FirebaseApp} instance. * * When called with no arguments, the default app is returned. When an app name * is provided, the app corresponding to that name is returned. diff --git a/packages-exp/app-exp/src/public-types.ts b/packages-exp/app-exp/src/public-types.ts index a16e6a8b352..e153c6eb4ef 100644 --- a/packages-exp/app-exp/src/public-types.ts +++ b/packages-exp/app-exp/src/public-types.ts @@ -19,7 +19,7 @@ import { ComponentContainer } from '@firebase/component'; import { PlatformLoggerService, VersionService } from './types'; /** - * A FirebaseApp holds the initialization information for a collection of + * A {@link @firebase/app#FirebaseApp} holds the initialization information for a collection of * services. * * Do not call this constructor directly. Instead, use diff --git a/packages-exp/auth-exp/api-extractor.json b/packages-exp/auth-exp/api-extractor.json index 0be9d1870b4..af24f61f9b9 100644 --- a/packages-exp/auth-exp/api-extractor.json +++ b/packages-exp/auth-exp/api-extractor.json @@ -1,7 +1,7 @@ { "extends": "../../config/api-extractor.json", // Point it to your entry point d.ts file. - "mainEntryPointFilePath": "/dist/esm5/index.d.ts", + "mainEntryPointFilePath": "/dist/esm5/index.doc.d.ts", "dtsRollup": { "enabled": true, "untrimmedFilePath": "/dist/.d.ts", diff --git a/packages-exp/auth-exp/index.rn.ts b/packages-exp/auth-exp/index.rn.ts index 64c80112616..a54d8e0a1ae 100644 --- a/packages-exp/auth-exp/index.rn.ts +++ b/packages-exp/auth-exp/index.rn.ts @@ -25,7 +25,7 @@ import { AsyncStorage } from 'react-native'; import { FirebaseApp, getApp, _getProvider } from '@firebase/app-exp'; -import { Auth } from './src/model/public_types'; +import { Auth, Persistence } from './src/model/public_types'; import { initializeAuth } from './src'; import { registerAuth } from './src/core/auth/register'; @@ -41,7 +41,7 @@ export * from './src'; * * @public */ -export const reactNativeLocalPersistence = +export const reactNativeLocalPersistence: Persistence = getReactNativePersistence(AsyncStorage); export function getAuth(app: FirebaseApp = getApp()): Auth { diff --git a/packages-exp/auth-exp/src/core/action_code_url.ts b/packages-exp/auth-exp/src/core/action_code_url.ts index 123ad6f7dde..f3d5c69bc1f 100644 --- a/packages-exp/auth-exp/src/core/action_code_url.ts +++ b/packages-exp/auth-exp/src/core/action_code_url.ts @@ -115,7 +115,7 @@ export class ActionCodeURL { /** * @param actionLink - The link from which to extract the URL. - * @returns The ActionCodeURL object, or null if the link is invalid. + * @returns The {@link ActionCodeURL} object, or null if the link is invalid. * * @internal */ @@ -139,7 +139,7 @@ export class ActionCodeURL { * otherwise returns null. * * @param link - The email action link string. - * @returns The ActionCodeURL object, or null if the link is invalid. + * @returns The {@link ActionCodeURL} object, or null if the link is invalid. * * @public */ diff --git a/packages-exp/auth-exp/src/core/auth/emulator.ts b/packages-exp/auth-exp/src/core/auth/emulator.ts index 69e465fd84f..166533e637a 100644 --- a/packages-exp/auth-exp/src/core/auth/emulator.ts +++ b/packages-exp/auth-exp/src/core/auth/emulator.ts @@ -20,7 +20,7 @@ import { _assert } from '../util/assert'; import { _castAuth } from './auth_impl'; /** - * Changes the Auth instance to communicate with the Firebase Auth Emulator, instead of production + * Changes the {@link Auth} instance to communicate with the Firebase Auth Emulator, instead of production * Firebase Auth services. * * @remarks @@ -34,9 +34,10 @@ import { _castAuth } from './auth_impl'; * connectAuthEmulator(auth, 'http://127.0.0.1:9099', { disableWarnings: true }); * ``` * - * @param auth - The Auth instance. + * @param auth - The {@link Auth} instance. * @param url - The URL at which the emulator is running (eg, 'http://localhost:9099'). - * @param options.disableWarnings - (Optional: default false) Disable the warning banner attached to the DOM + * @param options - Optional. `options.disableWarnings` defaults to `false`. Set it to + * `true` to disable the warning banner attached to the DOM. * * @public */ diff --git a/packages-exp/auth-exp/src/core/auth/initialize.ts b/packages-exp/auth-exp/src/core/auth/initialize.ts index 8f8528969eb..7ac8323d9b3 100644 --- a/packages-exp/auth-exp/src/core/auth/initialize.ts +++ b/packages-exp/auth-exp/src/core/auth/initialize.ts @@ -26,12 +26,12 @@ import { _getInstance } from '../util/instantiator'; import { AuthImpl } from './auth_impl'; /** - * Initializes an Auth instance with fine-grained control over + * Initializes an {@link Auth} instance with fine-grained control over * {@link Dependencies}. * * @remarks * - * This function allows more control over the Auth instance than + * This function allows more control over the {@link 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 @@ -39,7 +39,7 @@ import { AuthImpl } from './auth_impl'; * 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: + * accounts saved for the current session, initialize `Auth` with: * * ```js * const auth = initializeAuth(app, { diff --git a/packages-exp/auth-exp/src/core/errors.ts b/packages-exp/auth-exp/src/core/errors.ts index a79ecca7292..78b76caacc5 100644 --- a/packages-exp/auth-exp/src/core/errors.ts +++ b/packages-exp/auth-exp/src/core/errors.ts @@ -436,7 +436,7 @@ export const _DEFAULT_AUTH_ERROR_FACTORY = new ErrorFactory< >('auth', 'Firebase', _prodErrorMap()); /** - * A map of potential Auth error codes, for easier comparison with errors + * A map of potential `Auth` error codes, for easier comparison with errors * thrown by the SDK. * * @remarks diff --git a/packages-exp/auth-exp/src/core/index.ts b/packages-exp/auth-exp/src/core/index.ts index 7053b2f9bb9..473475f7c38 100644 --- a/packages-exp/auth-exp/src/core/index.ts +++ b/packages-exp/auth-exp/src/core/index.ts @@ -34,13 +34,13 @@ export { // Non-optional auth methods. /** - * 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 + * Changes the type of persistence on the {@link 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. * * @remarks * 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 + * 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. * * @example @@ -48,9 +48,9 @@ export { * setPersistence(auth, browserSessionPersistence); * ``` * - * @param auth - The Auth instance. + * @param auth - The {@link Auth} instance. * @param persistence - The {@link Persistence} to use. - * @returns A promise that resolves once the persistence change has completed + * @returns A `Promise` that resolves once the persistence change has completed * * @public */ @@ -64,7 +64,7 @@ export function setPersistence( * Adds an observer for changes to the signed-in user's ID token, which includes sign-in, * sign-out, and token refresh events. * - * @param auth - The Auth instance. + * @param auth - The {@link Auth} instance. * @param nextOrObserver - callback triggered on change. * @param error - callback triggered on error. * @param completed - callback triggered when observer is removed. @@ -89,7 +89,7 @@ export function onIdTokenChanged( * @remarks * To keep the old behavior, see {@link onIdTokenChanged}. * - * @param auth - The Auth instance. + * @param auth - The {@link Auth} instance. * @param nextOrObserver - callback triggered on change. * @param error - callback triggered on error. * @param completed - callback triggered when observer is removed. @@ -111,7 +111,7 @@ export function onAuthStateChanged( /** * Sets the current language to the default device/browser preference. * - * @param auth - The Auth instanec. + * @param auth - The {@link Auth} instance. * * @public */ @@ -131,7 +131,7 @@ export function useDeviceLanguage(auth: Auth): void { * The operation fails with an error if the user to be updated belongs to a different Firebase * project. * - * @param auth - The Auth instance. + * @param auth - The {@link Auth} instance. * @param user - The new {@link User}. * * @public @@ -145,7 +145,7 @@ export function updateCurrentUser( /** * Signs out the current user. * - * @param auth - The Auth instance. + * @param auth - The {@link Auth} instance. * * @public */ diff --git a/packages-exp/auth-exp/src/core/providers/email.ts b/packages-exp/auth-exp/src/core/providers/email.ts index 81382b15aa9..1cf9a48da1e 100644 --- a/packages-exp/auth-exp/src/core/providers/email.ts +++ b/packages-exp/auth-exp/src/core/providers/email.ts @@ -87,7 +87,7 @@ export class EmailAuthProvider implements AuthProvider { * const userCredential = await signInWithEmailLink(auth, email, emailLink); * ``` * - * @param auth - The Auth instance used to verify the link. + * @param auth - The {@link Auth} instance used to verify the link. * @param email - Email address. * @param emailLink - Sign-in email link. * @returns - The auth provider credential. diff --git a/packages-exp/auth-exp/src/core/providers/oauth.ts b/packages-exp/auth-exp/src/core/providers/oauth.ts index be8a8a6e985..17f510cd727 100644 --- a/packages-exp/auth-exp/src/core/providers/oauth.ts +++ b/packages-exp/auth-exp/src/core/providers/oauth.ts @@ -62,7 +62,8 @@ export interface OAuthCredentialOptions { */ export abstract class BaseOAuthProvider extends FederatedAuthProvider - implements AuthProvider { + implements AuthProvider +{ /** @internal */ private scopes: string[] = []; @@ -130,7 +131,7 @@ export abstract class BaseOAuthProvider 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 + * @param json - A plain object or a JSON string */ static credentialFromJSON(json: object | string): OAuthCredential { const obj = typeof json === 'string' ? JSON.parse(json) : json; diff --git a/packages-exp/auth-exp/src/core/providers/saml.ts b/packages-exp/auth-exp/src/core/providers/saml.ts index e4378bb6d48..f6fb0a56811 100644 --- a/packages-exp/auth-exp/src/core/providers/saml.ts +++ b/packages-exp/auth-exp/src/core/providers/saml.ts @@ -29,14 +29,14 @@ import { FederatedAuthProvider } from './federated'; const SAML_PROVIDER_PREFIX = 'saml.'; /** - * An AuthProvider for SAML. + * An {@link AuthProvider} for SAML. * * @public */ export class SAMLAuthProvider extends FederatedAuthProvider { /** * Constructor. The providerId must start with "saml." - * @param - providerId + * @param providerId - SAML provider ID. */ constructor(providerId: string) { _assert( @@ -60,7 +60,7 @@ export class SAMLAuthProvider extends FederatedAuthProvider { * const credential = SAMLAuthProvider.credentialFromResult(userCredential); * ``` * - * @param userCredential + * @param userCredential - The user credential. */ static credentialFromResult( userCredential: UserCredential @@ -84,7 +84,7 @@ export class SAMLAuthProvider extends FederatedAuthProvider { /** * Creates an {@link AuthCredential} from a JSON string or a plain object. - * @param json A plain object or a JSON string + * @param json - A plain object or a JSON string */ static credentialFromJSON(json: string | object): AuthCredential { const credential = SAMLAuthCredential.fromJSON(json); diff --git a/packages-exp/auth-exp/src/core/strategies/anonymous.ts b/packages-exp/auth-exp/src/core/strategies/anonymous.ts index 5233e1bb52e..cd2a40f8240 100644 --- a/packages-exp/auth-exp/src/core/strategies/anonymous.ts +++ b/packages-exp/auth-exp/src/core/strategies/anonymous.ts @@ -29,7 +29,7 @@ import { OperationType } from '../../model/enums'; * If there is already an anonymous user signed in, that user will be returned; otherwise, a * new anonymous user identity will be created and returned. * - * @param auth - The Auth instance. + * @param auth - The {@link Auth} instance. * * @public */ diff --git a/packages-exp/auth-exp/src/core/strategies/credential.ts b/packages-exp/auth-exp/src/core/strategies/credential.ts index 3e77eef37cb..4d24c758fb9 100644 --- a/packages-exp/auth-exp/src/core/strategies/credential.ts +++ b/packages-exp/auth-exp/src/core/strategies/credential.ts @@ -57,7 +57,7 @@ export async function _signInWithCredential( * @remarks * An {@link AuthProvider} can be used to generate the credential. * - * @param auth - The Auth instance. + * @param auth - The {@link Auth} instance. * @param credential - The auth credential. * * @public @@ -96,7 +96,7 @@ export async function linkWithCredential( * * @remarks * Use before operations such as {@link updatePassword} that require tokens from recent sign-in - * attempts. This method can be used to recover from a CREDENTIAL_TOO_OLD_LOGIN_AGAIN error. + * attempts. This method can be used to recover from a `CREDENTIAL_TOO_OLD_LOGIN_AGAIN` error. * * @param user - The user. * @param credential - The auth credential. diff --git a/packages-exp/auth-exp/src/core/strategies/custom_token.ts b/packages-exp/auth-exp/src/core/strategies/custom_token.ts index 65c4707eaba..6d1e1b36fe0 100644 --- a/packages-exp/auth-exp/src/core/strategies/custom_token.ts +++ b/packages-exp/auth-exp/src/core/strategies/custom_token.ts @@ -34,7 +34,7 @@ import { OperationType } from '../../model/enums'; * * Fails with an error if the token is invalid, expired, or not accepted by the Firebase Auth service. * - * @param auth - The Auth instance. + * @param auth - The {@link Auth} instance. * @param customToken - The custom token to sign in with. * * @public diff --git a/packages-exp/auth-exp/src/core/strategies/email.ts b/packages-exp/auth-exp/src/core/strategies/email.ts index 70dee6febc6..43d3804eace 100644 --- a/packages-exp/auth-exp/src/core/strategies/email.ts +++ b/packages-exp/auth-exp/src/core/strategies/email.ts @@ -41,7 +41,7 @@ import { getModularInstance } from '@firebase/util'; * {@link SignInMethod}.EMAIL_PASSWORD and * {@link SignInMethod}.EMAIL_LINK. * - * @param auth - The Auth instance. + * @param auth - The {@link Auth} instance. * @param email - The user's email address. * * @public diff --git a/packages-exp/auth-exp/src/core/strategies/email_and_password.ts b/packages-exp/auth-exp/src/core/strategies/email_and_password.ts index bce6334b3be..9d968fa2719 100644 --- a/packages-exp/auth-exp/src/core/strategies/email_and_password.ts +++ b/packages-exp/auth-exp/src/core/strategies/email_and_password.ts @@ -63,7 +63,7 @@ import { OperationType } from '../../model/enums'; * await confirmPasswordReset('user@example.com', code); * ``` * - * @param auth - The Auth instance. + * @param auth - The {@link Auth} instance. * @param email - The user's email address. * @param actionCodeSettings - The {@link ActionCodeSettings}. * @@ -89,7 +89,7 @@ export async function sendPasswordResetEmail( /** * Completes the password reset process, given a confirmation code and new password. * - * @param auth - The Auth instance. + * @param auth - The {@link Auth} instance. * @param oobCode - A confirmation code sent to the user. * @param newPassword - The new password. * @@ -110,7 +110,7 @@ export async function confirmPasswordReset( /** * Applies a verification code sent to the user by email or other out-of-band mechanism. * - * @param auth - The Auth instance. + * @param auth - The {@link Auth} instance. * @param oobCode - A verification code sent to the user. * * @public @@ -127,7 +127,7 @@ export async function applyActionCode( * * @returns metadata about the code. * - * @param auth - The Auth instance. + * @param auth - The {@link Auth} instance. * @param oobCode - A verification code sent to the user. * * @public @@ -190,7 +190,7 @@ export async function checkActionCode( * * @returns the user's email address if valid. * - * @param auth - The Auth instance. + * @param auth - The {@link Auth} instance. * @param code - A verification code sent to the user. * * @public @@ -215,7 +215,7 @@ export async function verifyPasswordResetCode( * Note: The email address acts as a unique identifier for the user and enables an email-based * password reset. This function will create a new user account and set the initial user password. * - * @param auth - The Auth instance. + * @param auth - The {@link Auth} instance. * @param email - The user's email address. * @param password - The user's chosen password. * @@ -253,7 +253,7 @@ export async function createUserWithEmailAndPassword( * email address serves as a unique identifier for the user, and the password is used to access * the user's account in your Firebase project. See also: {@link createUserWithEmailAndPassword}. * - * @param auth - The Auth instance. + * @param auth - The {@link Auth} instance. * @param email - The users email address. * @param password - The users password. * diff --git a/packages-exp/auth-exp/src/core/strategies/email_link.ts b/packages-exp/auth-exp/src/core/strategies/email_link.ts index 31707296ef2..a46c3f8637d 100644 --- a/packages-exp/auth-exp/src/core/strategies/email_link.ts +++ b/packages-exp/auth-exp/src/core/strategies/email_link.ts @@ -64,7 +64,7 @@ import { getModularInstance } from '@firebase/util'; * } * ``` * - * @param authInternal - The Auth instance. + * @param authInternal - The {@link Auth} instance. * @param email - The user's email address. * @param actionCodeSettings - The {@link ActionCodeSettings}. * @@ -95,7 +95,7 @@ export async function sendSignInLinkToEmail( /** * Checks if an incoming link is a sign-in with email link suitable for {@link signInWithEmailLink}. * - * @param auth - The Auth instance. + * @param auth - The {@link Auth} instance. * @param emailLink - The link sent to the user's email address. * * @public @@ -136,7 +136,7 @@ export function isSignInWithEmailLink(auth: Auth, emailLink: string): boolean { * } * ``` * - * @param auth - The Auth instance. + * @param auth - The {@link Auth} instance. * @param email - The user's email address. * @param emailLink - The link sent to the user's email address. * diff --git a/packages-exp/auth-exp/src/mfa/mfa_resolver.ts b/packages-exp/auth-exp/src/mfa/mfa_resolver.ts index 89dd5d0e05a..278d6167011 100644 --- a/packages-exp/auth-exp/src/mfa/mfa_resolver.ts +++ b/packages-exp/auth-exp/src/mfa/mfa_resolver.ts @@ -117,7 +117,7 @@ export class MultiFactorResolverImpl implements MultiFactorResolver { * Provides a {@link MultiFactorResolver} suitable for completion of a * multi-factor flow. * - * @param auth - The auth instance. + * @param auth - The {@link Auth} instance. * @param error - The {@link MultiFactorError} raised during a sign-in, or * reauthentication operation. * diff --git a/packages-exp/auth-exp/src/model/public_types.ts b/packages-exp/auth-exp/src/model/public_types.ts index 4c31ae75317..c7a24f18572 100644 --- a/packages-exp/auth-exp/src/model/public_types.ts +++ b/packages-exp/auth-exp/src/model/public_types.ts @@ -33,7 +33,7 @@ import { export { CompleteFn, ErrorFn, NextFn, Unsubscribe }; /** - * Interface representing the Auth config. + * Interface representing the `Auth` config. * * @public */ @@ -67,8 +67,8 @@ export interface Config { /** * Interface representing reCAPTCHA parameters. * - * See the [reCAPTCHA docs](https://developers.google.com/recaptcha/docs/display#render_param) - * for the list of accepted parameters. All parameters are accepted except for `sitekey`: Firebase Auth + * See the [reCAPTCHA docs](https://developers.google.com/recaptcha/docs/display#render_param) + * for the list of accepted parameters. All parameters are accepted except for `sitekey`: Firebase Auth * provisions a reCAPTCHA for each project and will configure the site key upon rendering. * * For an invisible reCAPTCHA, set the `size` key to `invisible`. @@ -115,7 +115,7 @@ export interface ParsedToken { export type NextOrObserver = NextFn | Observer; /** - * Interface for an Auth error. + * Interface for an `Auth` error. * * @public */ @@ -138,7 +138,7 @@ export interface AuthError extends FirebaseError { } /** - * Interface representing an Auth instance's settings. + * Interface representing an {@link Auth} instance's settings. * * @remarks Currently used for enabling/disabling app verification for phone Auth testing. * @@ -175,7 +175,7 @@ export interface Auth { /** The {@link Config} used to initialize this instance. */ readonly config: Config; /** - * Changes the type of persistence on the Auth instance. + * Changes the type of persistence on the {@link Auth} instance. * * @remarks * This will affect the currently saved Auth session and applies this type of persistence for @@ -194,7 +194,7 @@ export interface Auth { */ setPersistence(persistence: Persistence): Promise; /** - * The Auth instance's language code. + * The {@link Auth} instance's language code. * * @remarks * This is a readable/writable property. When set to null, the default Firebase Console language @@ -205,10 +205,10 @@ export interface Auth { */ languageCode: string | null; /** - * The Auth instance's tenant ID. + * The {@link Auth} instance's tenant ID. * * @remarks - * This is a readable/writable property. When you set the tenant ID of an Auth instance, all + * This is a readable/writable property. When you set the tenant ID of an {@link 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. * @@ -226,7 +226,7 @@ export interface Auth { */ tenantId: string | null; /** - * The Auth instance's settings. + * The {@link Auth} instance's settings. * * @remarks * This is used to edit/read configuration related options such as app verification mode for @@ -311,7 +311,7 @@ export interface Persistence { * Interface representing ID token result obtained from {@link User.getIdTokenResult}. * * @remarks - * It contains the ID token JWT string and other helper properties for getting different data + * `IdTokenResult` contains the ID token JWT string and other helper properties for getting different data * associated with the token as well as all the decoded payload claims. * * Note that these claims are not to be trusted as they are parsed client side. Only server side @@ -795,7 +795,7 @@ export interface MultiFactorUser { * ``` * * @param option - The multi-factor option to unenroll. - * @returns - A promise which resolves when the unenroll operation is complete. + * @returns - A `Promise` which resolves when the unenroll operation is complete. */ unenroll(option: MultiFactorInfo | string): Promise; } @@ -866,7 +866,7 @@ export interface PhoneMultiFactorSignInInfoOptions { } /** - * Interface for a supplied AsyncStorage. + * Interface for a supplied `AsyncStorage`. * * @public */ @@ -1101,6 +1101,7 @@ declare module '@firebase/component' { /** * Configuration of Firebase Authentication Emulator. + * @public */ export interface EmulatorConfig { /** @@ -1149,7 +1150,7 @@ export interface EmulatorConfig { export interface AuthErrorMap {} /** - * The dependencies that can be used to initialize an Auth instance. + * The dependencies that can be used to initialize an {@link Auth} instance. * * @remarks * @@ -1160,7 +1161,7 @@ export interface AuthErrorMap {} * {@link cordovaPopupRedirectResolver}. The dependencies object is how Auth is * configured to reduce bundle sizes. * - * There are two ways to initialize an auth instance: {@link getAuth} and + * There are two ways to initialize an {@link Auth} instance: {@link getAuth} and * {@link initializeAuth}. `getAuth` initializes everything using * platform-specific configurations, while `initializeAuth` takes a * `Dependencies` object directly, giving you more control over what is used. diff --git a/packages-exp/auth-exp/src/platform_browser/persistence/indexed_db.ts b/packages-exp/auth-exp/src/platform_browser/persistence/indexed_db.ts index eddb30fddf7..a9231c0870d 100644 --- a/packages-exp/auth-exp/src/platform_browser/persistence/indexed_db.ts +++ b/packages-exp/auth-exp/src/platform_browser/persistence/indexed_db.ts @@ -443,7 +443,7 @@ class IndexedDBLocalPersistence implements InternalPersistence { } /** - * An implementation of {@link Persistence} of type 'LOCAL' using `indexedDB` + * An implementation of {@link Persistence} of type `LOCAL` using `indexedDB` * for the underlying storage. * * @public diff --git a/packages-exp/auth-exp/src/platform_browser/persistence/local_storage.ts b/packages-exp/auth-exp/src/platform_browser/persistence/local_storage.ts index 3265ffd7b05..efde4fe0dc5 100644 --- a/packages-exp/auth-exp/src/platform_browser/persistence/local_storage.ts +++ b/packages-exp/auth-exp/src/platform_browser/persistence/local_storage.ts @@ -260,7 +260,7 @@ class BrowserLocalPersistence } /** - * An implementation of {@link Persistence} of type 'LOCAL' using `localStorage` + * An implementation of {@link Persistence} of type `LOCAL` using `localStorage` * for the underlying storage. * * @public diff --git a/packages-exp/auth-exp/src/platform_browser/persistence/session_storage.ts b/packages-exp/auth-exp/src/platform_browser/persistence/session_storage.ts index ddce0fd414e..5c8797cbe8d 100644 --- a/packages-exp/auth-exp/src/platform_browser/persistence/session_storage.ts +++ b/packages-exp/auth-exp/src/platform_browser/persistence/session_storage.ts @@ -26,7 +26,8 @@ import { BrowserPersistenceClass } from './browser'; class BrowserSessionPersistence extends BrowserPersistenceClass - implements InternalPersistence { + implements InternalPersistence +{ static type: 'SESSION' = 'SESSION'; constructor() { @@ -45,7 +46,7 @@ class BrowserSessionPersistence } /** - * An implementation of {@link Persistence} of 'SESSION' using `sessionStorage` + * An implementation of {@link Persistence} of `SESSION` using `sessionStorage` * for the underlying storage. * * @public diff --git a/packages-exp/auth-exp/src/platform_browser/providers/phone.ts b/packages-exp/auth-exp/src/platform_browser/providers/phone.ts index 41696066837..f5018592325 100644 --- a/packages-exp/auth-exp/src/platform_browser/providers/phone.ts +++ b/packages-exp/auth-exp/src/platform_browser/providers/phone.ts @@ -61,7 +61,7 @@ export class PhoneAuthProvider { private readonly auth: AuthInternal; /** - * @param auth - The Firebase Auth instance in which sign-ins should occur. + * @param auth - The Firebase {@link Auth} instance in which sign-ins should occur. * */ constructor(auth: Auth) { @@ -149,7 +149,7 @@ export class PhoneAuthProvider { /** * Generates an {@link AuthCredential} from a {@link UserCredential}. - * @param userCredential + * @param userCredential - The user credential. */ static credentialFromResult( userCredential: UserCredential @@ -188,7 +188,7 @@ export class PhoneAuthProvider { * // At this point, auth.currentUser.phoneNumber === number. * ``` * - * @param error + * @param error - The error to generate a credential from. */ static credentialFromError(error: FirebaseError): AuthCredential | null { return PhoneAuthProvider.credentialFromTaggedObject( diff --git a/packages-exp/auth-exp/src/platform_browser/recaptcha/recaptcha_verifier.ts b/packages-exp/auth-exp/src/platform_browser/recaptcha/recaptcha_verifier.ts index ea64cf6783e..792c2fd902a 100644 --- a/packages-exp/auth-exp/src/platform_browser/recaptcha/recaptcha_verifier.ts +++ b/packages-exp/auth-exp/src/platform_browser/recaptcha/recaptcha_verifier.ts @@ -84,10 +84,10 @@ export class RecaptchaVerifier implements ApplicationVerifierInternal { * configure this upon rendering. For an invisible reCAPTCHA, a size key must have the value * 'invisible'. * - * @param authExtern - The corresponding Firebase Auth instance. + * @param authExtern - The corresponding Firebase {@link Auth} instance. * * @remarks - * If none is provided, the default Firebase Auth instance is used. A Firebase Auth instance + * If none is provided, the default Firebase {@link Auth} instance is used. A Firebase {@link Auth} instance * must be initialized with an API key, otherwise an error will be thrown. */ constructor( diff --git a/packages-exp/auth-exp/src/platform_browser/strategies/phone.ts b/packages-exp/auth-exp/src/platform_browser/strategies/phone.ts index 6fb334d85df..90ed1bea427 100644 --- a/packages-exp/auth-exp/src/platform_browser/strategies/phone.ts +++ b/packages-exp/auth-exp/src/platform_browser/strategies/phone.ts @@ -88,7 +88,7 @@ class ConfirmationResultImpl implements ConfirmationResult { * const credential = await confirmationResult.confirm(verificationCode); * ``` * - * @param auth - The Auth instance. + * @param auth - The {@link Auth} instance. * @param phoneNumber - The user's phone number in E.164 format (e.g. +16505550101). * @param appVerifier - The {@link ApplicationVerifier}. * @@ -137,7 +137,7 @@ export async function linkWithPhoneNumber( } /** - * Re-authenticates a user using a fresh phne credential. + * Re-authenticates a user using a fresh phone credential. * * @remarks Use before operations such as {@link updatePassword} that require tokens from recent sign-in attempts. * diff --git a/packages-exp/auth-exp/src/platform_browser/strategies/popup.ts b/packages-exp/auth-exp/src/platform_browser/strategies/popup.ts index b62801efb3e..c8e0665e8de 100644 --- a/packages-exp/auth-exp/src/platform_browser/strategies/popup.ts +++ b/packages-exp/auth-exp/src/platform_browser/strategies/popup.ts @@ -68,7 +68,7 @@ export const _POLL_WINDOW_CLOSE_TIMEOUT = new Delay(2000, 10000); * const token = credential.accessToken; * ``` * - * @param auth - The Auth instance. + * @param auth - The {@link Auth} instance. * @param provider - The provider to authenticate. The provider has to be an {@link OAuthProvider}. * Non-OAuth providers like {@link EmailAuthProvider} will throw an error. * @param resolver - An instance of {@link PopupRedirectResolver}, optional diff --git a/packages-exp/auth-exp/src/platform_browser/strategies/redirect.ts b/packages-exp/auth-exp/src/platform_browser/strategies/redirect.ts index d06eba48cf1..9eabe06f306 100644 --- a/packages-exp/auth-exp/src/platform_browser/strategies/redirect.ts +++ b/packages-exp/auth-exp/src/platform_browser/strategies/redirect.ts @@ -69,7 +69,7 @@ import { getModularInstance } from '@firebase/util'; * const operationType = result.operationType; * ``` * - * @param auth - The Auth instance. + * @param auth - The {@link Auth} instance. * @param provider - The provider to authenticate. The provider has to be an {@link OAuthProvider}. * Non-OAuth providers like {@link EmailAuthProvider} will throw an error. * @param resolver - An instance of {@link PopupRedirectResolver}, optional @@ -262,7 +262,7 @@ export async function _linkWithRedirect( * const operationType = result.operationType; * ``` * - * @param auth - The Auth instance. + * @param auth - The {@link Auth} instance. * @param resolver - An instance of {@link PopupRedirectResolver}, optional * if already supplied to {@link initializeAuth} or provided by {@link getAuth}. * diff --git a/packages-exp/functions-exp/src/api.ts b/packages-exp/functions-exp/src/api.ts index 01c54377e36..a1f91b48a7f 100644 --- a/packages-exp/functions-exp/src/api.ts +++ b/packages-exp/functions-exp/src/api.ts @@ -31,8 +31,8 @@ import { getModularInstance } from '@firebase/util'; export * from './public-types'; /** - * Returns a Functions instance for the given app. - * @param app - The FirebaseApp to use. + * Returns a {@link Functions} instance for the given app. + * @param app - The {@link @firebase/app#FirebaseApp} to use. * @param regionOrCustomDomain - one of: * a) The region the callable functions are located in (ex: us-central1) * b) A custom domain hosting the callable functions (ex: https://mydomain.com) @@ -75,7 +75,7 @@ export function connectFunctionsEmulator( } /** - * Returns a reference to the callable https trigger with the given name. + * Returns a reference to the callable HTTPS trigger with the given name. * @param name - The name of the trigger. * @public */ diff --git a/packages-exp/functions-exp/src/public-types.ts b/packages-exp/functions-exp/src/public-types.ts index e64f9dbe759..5fe37052c06 100644 --- a/packages-exp/functions-exp/src/public-types.ts +++ b/packages-exp/functions-exp/src/public-types.ts @@ -18,7 +18,7 @@ import { FirebaseApp } from '@firebase/app-exp'; import { FirebaseError } from '@firebase/util'; /** - * An HttpsCallableResult wraps a single result from a function call. + * An `HttpsCallableResult` wraps a single result from a function call. * @public */ export interface HttpsCallableResult { @@ -29,8 +29,7 @@ export interface HttpsCallableResult { } /** - * An HttpsCallable is a reference to a "callable" http trigger in - * Google Cloud Functions. + * A reference to a "callable" HTTP trigger in Google Cloud Functions. * @param data - Data to be passed to callable function. * @public */ @@ -39,7 +38,7 @@ export type HttpsCallable = ( ) => Promise>; /** - * HttpsCallableOptions specify metadata about how calls should be executed. + * An interface for metadata about how calls should be executed. * @public */ export interface HttpsCallableOptions { @@ -51,13 +50,12 @@ export interface HttpsCallableOptions { } /** - * `Functions` represents a Functions instance, and is a required argument for - * all Functions operations. + * A `Functions` instance. * @public */ export interface Functions { /** - * The FirebaseApp this Functions instance is associated with. + * The {@link @firebase/app#FirebaseApp} this `Functions` instance is associated with. */ app: FirebaseApp; diff --git a/packages-exp/installations-exp/src/api/get-installations.ts b/packages-exp/installations-exp/src/api/get-installations.ts index 30f013d54ef..777cb3fdc75 100644 --- a/packages-exp/installations-exp/src/api/get-installations.ts +++ b/packages-exp/installations-exp/src/api/get-installations.ts @@ -19,8 +19,9 @@ import { FirebaseApp, getApp, _getProvider } from '@firebase/app-exp'; import { Installations } from '../interfaces/public-types'; /** - * Returns an instance of FirebaseInstallations associated with the given FirebaseApp instance. - * @param app - The `FirebaseApp` instance. + * Returns an instance of {@link Installations} associated with the given + * {@link @firebase/app#FirebaseApp} instance. + * @param app - The {@link @firebase/app#FirebaseApp} instance. * * @public */ diff --git a/packages-exp/installations-exp/src/api/get-token.ts b/packages-exp/installations-exp/src/api/get-token.ts index 5b178b974f0..ca540019c2c 100644 --- a/packages-exp/installations-exp/src/api/get-token.ts +++ b/packages-exp/installations-exp/src/api/get-token.ts @@ -24,7 +24,8 @@ import { import { Installations } from '../interfaces/public-types'; /** - * Returns an Installation auth token, identifying the current Firebase Installation. + * Returns a Firebase Installations auth token, identifying the current + * Firebase Installation. * @param installations - The `Installations` instance. * @param forceRefresh - Force refresh regardless of token expiration. * diff --git a/packages-exp/installations-exp/src/interfaces/public-types.ts b/packages-exp/installations-exp/src/interfaces/public-types.ts index ddae5ddb3f5..d37aa69e6bb 100644 --- a/packages-exp/installations-exp/src/interfaces/public-types.ts +++ b/packages-exp/installations-exp/src/interfaces/public-types.ts @@ -16,7 +16,7 @@ */ /** - * Public interface of the FirebaseInstallations SDK. + * Public interface of the Firebase Installations SDK. * * @public */ diff --git a/packages-exp/messaging-exp/src/api.ts b/packages-exp/messaging-exp/src/api.ts index 33656615d0a..38d5083e2cd 100644 --- a/packages-exp/messaging-exp/src/api.ts +++ b/packages-exp/messaging-exp/src/api.ts @@ -60,14 +60,14 @@ export function getMessagingInSw(app: FirebaseApp = getApp()): Messaging { } /** - * Subscribes the `FirebaseMessaging` instance to push notifications. Returns an Firebase Cloud - * Messaging registration token that can be used to send push messages to that `FirebaseMessaging` + * Subscribes the {@link Messaging} instance to push notifications. Returns an Firebase Cloud + * Messaging registration token that can be used to send push messages to that {@link Messaging} * instance. * * If a notification permission isn't already granted, this method asks the user for permission. The * returned promise rejects if the user does not allow the app to show notifications. * - * @param messaging - The `FirebaseMessaging` instance. + * @param messaging - The {@link Messaging} instance. * @param options - Provides an optional vapid key and an optinoal service worker registration * * @returns The promise resolves with an FCM registration token. @@ -83,10 +83,10 @@ export async function getToken( } /** - * Deletes the registration token associated with this `FirebaseMessaging` instance and unsubscribes - * the `FirebaseMessaging` instance from the push subscription. + * Deletes the registration token associated with this {@link Messaging} instance and unsubscribes + * the {@link Messaging} instance from the push subscription. * - * @param messaging - The `FirebaseMessaging` instance. + * @param messaging - The {@link Messaging} instance. * * @returns The promise resolves when the token has been successfully deleted. * @@ -103,7 +103,7 @@ export function deleteToken(messaging: Messaging): Promise { * the push message. * * - * @param messaging - The `FirebaseMessaging` instance. + * @param messaging - The {@link Messaging} instance. * @param nextOrObserver - This function, or observer object with `next` defined, * is called when a message is received and the user is currently viewing your page. * @returns To stop listening for messages execute this returned function. @@ -122,7 +122,7 @@ export function onMessage( * Called when a message is received while the app is in the background. An app is considered to be * in the background if no active window is displayed. * - * @param messaging - The `FirebaseMessaging` instance. + * @param messaging - The {@link Messaging} instance. * @param nextOrObserver - This function, or observer object with `next` defined, is called when a * message is received and the app is currently in the background. * diff --git a/packages-exp/performance-exp/src/index.ts b/packages-exp/performance-exp/src/index.ts index 84470a5501d..d9d3ead78d4 100644 --- a/packages-exp/performance-exp/src/index.ts +++ b/packages-exp/performance-exp/src/index.ts @@ -50,8 +50,8 @@ import { deepEqual, getModularInstance } from '@firebase/util'; const DEFAULT_ENTRY_NAME = '[DEFAULT]'; /** - * Returns a FirebasePerformance instance for the given app. - * @param app - The `FirebaseApp` to use. + * Returns a {@link FirebasePerformance} instance for the given app. + * @param app - The {@link @firebase/app#FirebaseApp} to use. * @public */ export function getPerformance( @@ -64,9 +64,9 @@ export function getPerformance( } /** - * Returns a FirebasePerformance instance for the given app. Can only be called once. - * @param app - The `FirebaseApp` to use. - * @param settings - Optional settings for the `FirebasePerformance` instance. + * Returns a {@link FirebasePerformance} instance for the given app. Can only be called once. + * @param app - The {@link @firebase/app#FirebaseApp} to use. + * @param settings - Optional settings for the {@link FirebasePerformance} instance. * @public */ export function initializePerformance( @@ -96,7 +96,7 @@ export function initializePerformance( /** * Returns a new `PerformanceTrace` instance. - * @param performance - The `FirebasePerformance` instance to use. + * @param performance - The {@link FirebasePerformance} instance to use. * @param name - The name of the trace. * @public */ diff --git a/packages-exp/remote-config-exp/src/api.ts b/packages-exp/remote-config-exp/src/api.ts index bf7937faeb0..bbad3130f7a 100644 --- a/packages-exp/remote-config-exp/src/api.ts +++ b/packages-exp/remote-config-exp/src/api.ts @@ -31,8 +31,8 @@ import { getModularInstance } from '@firebase/util'; /** * - * @param app - The `FirebaseApp` instance. - * @returns A `RemoteConfig` instance. + * @param app - The {@link @firebase/app#FirebaseApp} instance. + * @returns A {@link RemoteConfig} instance. * * @public */ @@ -44,9 +44,9 @@ export function getRemoteConfig(app: FirebaseApp = getApp()): RemoteConfig { /** * Makes the last fetched config available to the getters. - * @param remoteConfig - The `RemoteConfig` instance. - * @returns A promise which resolves to true if the current call activated the fetched configs. - * If the fetched configs were already activated, the promise will resolve to false. + * @param remoteConfig - The {@link RemoteConfig} instance. + * @returns A `Promise` which resolves to true if the current call activated the fetched configs. + * If the fetched configs were already activated, the `Promise` will resolve to false. * * @public */ @@ -75,9 +75,9 @@ export async function activate(remoteConfig: RemoteConfig): Promise { /** * Ensures the last activated config are available to the getters. - * @param remoteConfig - The `RemoteConfig` instance. + * @param remoteConfig - The {@link RemoteConfig} instance. * - * @returns A promise that resolves when the last activated config is available to the getters. + * @returns A `Promise` that resolves when the last activated config is available to the getters. * @public */ export function ensureInitialized(remoteConfig: RemoteConfig): Promise { @@ -92,16 +92,16 @@ export function ensureInitialized(remoteConfig: RemoteConfig): Promise { /** * Fetches and caches configuration from the Remote Config service. - * @param remoteConfig - The `RemoteConfig` instance. + * @param remoteConfig - The {@link RemoteConfig} instance. * @public */ export async function fetchConfig(remoteConfig: RemoteConfig): Promise { const rc = getModularInstance(remoteConfig) as RemoteConfigImpl; // Aborts the request after the given timeout, causing the fetch call to - // reject with an AbortError. + // reject with an `AbortError`. // //

Aborting after the request completes is a no-op, so we don't need a - // corresponding clearTimeout. + // corresponding `clearTimeout`. // // Locating abort logic here because: // * it uses a developer setting (timeout) @@ -134,7 +134,7 @@ export async function fetchConfig(remoteConfig: RemoteConfig): Promise { /** * Gets all config. * - * @param remoteConfig - The `RemoteConfig` instance. + * @param remoteConfig - The {@link RemoteConfig} instance. * @returns All config. * * @public @@ -155,7 +155,7 @@ export function getAll(remoteConfig: RemoteConfig): Record { * * Convenience method for calling remoteConfig.getValue(key).asBoolean(). * - * @param remoteConfig - The `RemoteConfig` instance. + * @param remoteConfig - The {@link RemoteConfig} instance. * @param key - The name of the parameter. * * @returns The value for the given key as a boolean. @@ -170,7 +170,7 @@ export function getBoolean(remoteConfig: RemoteConfig, key: string): boolean { * * Convenience method for calling remoteConfig.getValue(key).asNumber(). * - * @param remoteConfig - The `RemoteConfig` instance. + * @param remoteConfig - The {@link RemoteConfig} instance. * @param key - The name of the parameter. * * @returns The value for the given key as a number. @@ -185,7 +185,7 @@ export function getNumber(remoteConfig: RemoteConfig, key: string): number { * Gets the value for the given key as a string. * Convenience method for calling remoteConfig.getValue(key).asString(). * - * @param remoteConfig - The `RemoteConfig` instance. + * @param remoteConfig - The {@link RemoteConfig} instance. * @param key - The name of the parameter. * * @returns The value for the given key as a string. @@ -199,7 +199,7 @@ export function getString(remoteConfig: RemoteConfig, key: string): string { /** * Gets the {@link Value} for the given key. * - * @param remoteConfig - The `RemoteConfig` instance. + * @param remoteConfig - The {@link RemoteConfig} instance. * @param key - The name of the parameter. * * @returns The value for the given key. @@ -230,7 +230,7 @@ export function getValue(remoteConfig: RemoteConfig, key: string): Value { /** * Defines the log level to use. * - * @param remoteConfig - The `RemoteConfig` instance. + * @param remoteConfig - The {@link RemoteConfig} instance. * @param logLevel - The log level to set. * * @public diff --git a/packages-exp/remote-config-exp/src/api2.ts b/packages-exp/remote-config-exp/src/api2.ts index 7d0689a8561..ca45119a0ef 100644 --- a/packages-exp/remote-config-exp/src/api2.ts +++ b/packages-exp/remote-config-exp/src/api2.ts @@ -25,10 +25,10 @@ import { getModularInstance } from '@firebase/util'; * * Performs fetch and activate operations, as a convenience. * - * @param remoteConfig - The remote config instance. + * @param remoteConfig - The {@link RemoteConfig} instance. * - * @returns A promise which resolves to true if the current call activated the fetched configs. - * If the fetched configs were already activated, the promise will resolve to false. + * @returns A `Promise` which resolves to true if the current call activated the fetched configs. + * If the fetched configs were already activated, the `Promise` will resolve to false. * * @public */ diff --git a/packages-exp/remote-config-exp/src/public_types.ts b/packages-exp/remote-config-exp/src/public_types.ts index 1b70e570612..b25004f8184 100644 --- a/packages-exp/remote-config-exp/src/public_types.ts +++ b/packages-exp/remote-config-exp/src/public_types.ts @@ -27,7 +27,7 @@ export interface RemoteConfig { settings: RemoteConfigSettings; /** - * Object containing default values for conigs. + * Object containing default values for configs. */ defaultConfig: { [key: string]: string | number | boolean }; diff --git a/packages/database/src/exp/Database.ts b/packages/database/src/exp/Database.ts index 152877b46ce..d59ca53e191 100644 --- a/packages/database/src/exp/Database.ts +++ b/packages/database/src/exp/Database.ts @@ -51,7 +51,7 @@ import { validateUrl } from '../core/util/validation'; import { ReferenceImpl } from './Reference_impl'; /** - * This variable is also defined in the firebase node.js admin SDK. Before + * This variable is also defined in the firebase Node.js Admin SDK. Before * modifying this definition, consult the definition in: * * https://github.com/firebase/firebase-admin-node @@ -61,7 +61,7 @@ import { ReferenceImpl } from './Reference_impl'; const FIREBASE_DATABASE_EMULATOR_HOST_VAR = 'FIREBASE_DATABASE_EMULATOR_HOST'; /** - * Creates and caches Repo instances. + * Creates and caches `Repo` instances. */ const repos: { [appName: string]: { @@ -70,12 +70,12 @@ const repos: { } = {}; /** - * If true, new Repos will be created to use ReadonlyRestClient (for testing purposes). + * If true, any new `Repo` will be created to use `ReadonlyRestClient` (for testing purposes). */ let useRestClient = false; /** - * Update an existing repo in place to point to a new host/port. + * Update an existing `Repo` in place to point to a new host/port. */ function repoManagerApplyEmulatorSettings( repo: Repo, @@ -220,7 +220,7 @@ export function repoManagerForceRestClient(forceRestClient: boolean): void { * Class representing a Firebase Realtime Database. */ export class Database implements _FirebaseService { - /** Represents a database instance. */ + /** Represents a `Database` instance. */ readonly 'type' = 'database'; /** Track if the instance has been used (root or repo accessed) */ @@ -232,7 +232,7 @@ export class Database implements _FirebaseService { /** @hideconstructor */ constructor( public _repoInternal: Repo, - /** The FirebaseApp associated with this Realtime Database instance. */ + /** The {@link @firebase/app#FirebaseApp} associated with this Realtime Database instance. */ readonly app: FirebaseApp ) {} @@ -281,7 +281,7 @@ export class Database implements _FirebaseService { * Database instance is associated with. * @param url - The URL of the Realtime Database instance to connect to. If not * provided, the SDK connects to the default instance of the Firebase App. - * @returns The `FirebaseDatabase` instance of the provided app. + * @returns The `Database` instance of the provided app. */ export function getDatabase( app: FirebaseApp = getApp(), diff --git a/packages/database/src/exp/Reference.ts b/packages/database/src/exp/Reference.ts index 8a17476921f..c2e97aa229e 100644 --- a/packages/database/src/exp/Reference.ts +++ b/packages/database/src/exp/Reference.ts @@ -114,7 +114,7 @@ export interface DatabaseReference extends Query { /** * A `Promise` that can also act as a `DatabaseReference` when returned by - * {@link push}. The reference is available immediately and the Promise resolves + * {@link push}. The reference is available immediately and the `Promise` resolves * as the write to the backend completes. */ export interface ThenableReference diff --git a/packages/database/src/exp/Reference_impl.ts b/packages/database/src/exp/Reference_impl.ts index 5a8935849f5..1b363f2bbe9 100644 --- a/packages/database/src/exp/Reference_impl.ts +++ b/packages/database/src/exp/Reference_impl.ts @@ -803,7 +803,7 @@ export function update(ref: DatabaseReference, values: object): Promise { * Gets the most up-to-date result for this query. * * @param query - The query to run. - * @returns A promise which resolves to the resulting DataSnapshot if a value is + * @returns A `Promise` which resolves to the resulting DataSnapshot if a value is * available, or rejects if the client is unable to return a value (e.g., if the * server is unreachable and there is nothing cached). */ diff --git a/packages/database/src/exp/Transaction.ts b/packages/database/src/exp/Transaction.ts index 593a694b7c9..ca797a7dc1c 100644 --- a/packages/database/src/exp/Transaction.ts +++ b/packages/database/src/exp/Transaction.ts @@ -37,7 +37,7 @@ export interface TransactionOptions { } /** - * A type for the resolve value of Firebase.transaction. + * A type for the resolve value of {@link runTransaction}. */ export class TransactionResult { /** @hideconstructor */ @@ -58,7 +58,7 @@ export class TransactionResult { * Atomically modifies the data at this location. * * Atomically modify the data at this location. Unlike a normal `set()`, which - * just overwrites the data regardless of its previous value, `transaction()` is + * just overwrites the data regardless of its previous value, `runTransaction()` is * used to modify the existing value to a new value, ensuring there are no * conflicts with other clients writing to the same location at the same time. * @@ -72,7 +72,7 @@ export class TransactionResult { * * Note: Modifying data with `set()` will cancel any pending transactions at * that location, so extreme care should be taken if mixing `set()` and - * `transaction()` to update the same data. + * `runTransaction()` to update the same data. * * Note: When using transactions with Security and Firebase Rules in place, be * aware that a client needs `.read` access in addition to `.write` access in @@ -88,7 +88,7 @@ export class TransactionResult { * transaction will be aborted and the data at this location will not be * modified. * @param options - An options object to configure transactions. - * @returns A Promise that can optionally be used instead of the onComplete + * @returns A `Promise` that can optionally be used instead of the `onComplete` * callback to handle success and failure. */ export function runTransaction( diff --git a/packages/firestore/src/exp/database.ts b/packages/firestore/src/exp/database.ts index 9b29a79c254..e49d8870897 100644 --- a/packages/firestore/src/exp/database.ts +++ b/packages/firestore/src/exp/database.ts @@ -71,7 +71,7 @@ const DOM_EXCEPTION_QUOTA_EXCEEDED = 22; /** * Constant used to indicate the LRU garbage collection should be disabled. * Set this value as the `cacheSizeBytes` on the settings passed to the - * `Firestore` instance. + * {@link Firestore} instance. */ export const CACHE_SIZE_UNLIMITED = LRU_COLLECTION_DISABLED; @@ -82,7 +82,7 @@ export const CACHE_SIZE_UNLIMITED = LRU_COLLECTION_DISABLED; */ export class Firestore extends LiteFirestore { /** - * Whether it's a Firestore or Firestore Lite instance. + * Whether it's a {@link Firestore} or Firestore Lite instance. */ type: 'firestore-lite' | 'firestore' = 'firestore'; @@ -112,15 +112,15 @@ export class Firestore extends LiteFirestore { } /** - * Initializes a new instance of Cloud Firestore with the provided settings. + * Initializes a new instance of {@link Firestore} with the provided settings. * Can only be called before any other function, including * {@link getFirestore}. If the custom settings are empty, this function is * equivalent to calling {@link getFirestore}. * - * @param app - The {@link @firebase/app#FirebaseApp} with which the `Firestore` instance will + * @param app - The {@link @firebase/app#FirebaseApp} with which the {@link Firestore} instance will * be associated. - * @param settings - A settings object to configure the `Firestore` instance. - * @returns A newly initialized `Firestore` instance. + * @param settings - A settings object to configure the {@link Firestore} instance. + * @returns A newly initialized {@link Firestore} instance. */ export function initializeFirestore( app: FirebaseApp, @@ -159,13 +159,13 @@ export function initializeFirestore( } /** - * Returns the existing instance of Firestore that is associated with the + * Returns the existing {@link Firestore} instance that is associated with the * provided {@link @firebase/app#FirebaseApp}. If no instance exists, initializes a new * instance with default settings. * - * @param app - The {@link @firebase/app#FirebaseApp} instance that the returned Firestore + * @param app - The {@link @firebase/app#FirebaseApp} instance that the returned {@link Firestore} * instance is associated with. - * @returns The `Firestore` instance of the provided app. + * @returns The {@link Firestore} instance of the provided app. */ export function getFirestore(app: FirebaseApp = getApp()): Firestore { return _getProvider(app, 'firestore-exp').getImmediate() as Firestore; @@ -213,7 +213,7 @@ export function configureFirestore(firestore: Firestore): void { * {@link clearIndexedDbPersistence}. * * If this fails, `enableIndexedDbPersistence()` will reject the promise it - * returns. Note that even after this failure, the `Firestore` instance will + * returns. Note that even after this failure, the {@link Firestore} instance will * remain usable, however offline persistence will be disabled. * * There are several reasons why this can fail, which can be identified by @@ -223,10 +223,10 @@ export function configureFirestore(firestore: Firestore): void { * * unimplemented: The browser is incompatible with the offline * persistence implementation. * - * @param firestore - The `Firestore` instance to enable persistence for. + * @param firestore - The {@link Firestore} instance to enable persistence for. * @param persistenceSettings - Optional settings object to configure * persistence. - * @returns A promise that represents successfully enabling persistent storage. + * @returns A `Promise` that represents successfully enabling persistent storage. */ export function enableIndexedDbPersistence( firestore: Firestore, @@ -258,7 +258,7 @@ export function enableIndexedDbPersistence( * across all connected instances. * * If this fails, `enableMultiTabIndexedDbPersistence()` will reject the promise - * it returns. Note that even after this failure, the `Firestore` instance will + * it returns. Note that even after this failure, the {@link Firestore} instance will * remain usable, however offline persistence will be disabled. * * There are several reasons why this can fail, which can be identified by @@ -269,8 +269,8 @@ export function enableIndexedDbPersistence( * * unimplemented: The browser is incompatible with the offline * persistence implementation. * - * @param firestore - The `Firestore` instance to enable persistence for. - * @returns A promise that represents successfully enabling persistent + * @param firestore - The {@link Firestore} instance to enable persistence for. + * @returns A `Promise` that represents successfully enabling persistent * storage. */ export function enableMultiTabIndexedDbPersistence( @@ -369,10 +369,10 @@ function canFallbackFromIndexedDbError( * Clears the persistent storage. This includes pending writes and cached * documents. * - * Must be called while the `Firestore` instance is not started (after the app is + * Must be called while the {@link Firestore} instance is not started (after the app is * terminated or when the app is first initialized). On startup, this function * must be called before other functions (other than {@link - * initializeFirestore} or {@link getFirestore})). If the `Firestore` + * initializeFirestore} or {@link getFirestore})). If the {@link Firestore} * instance is still running, the promise will be rejected with the error code * of `failed-precondition`. * @@ -383,8 +383,8 @@ function canFallbackFromIndexedDbError( * to the disclosure of cached data in between user sessions, we strongly * recommend not enabling persistence at all. * - * @param firestore - The `Firestore` instance to clear persistence for. - * @returns A promise that is resolved when the persistent storage is + * @param firestore - The {@link Firestore} instance to clear persistence for. + * @returns A `Promise` that is resolved when the persistent storage is * cleared. Otherwise, the promise is rejected with an error. */ export function clearIndexedDbPersistence(firestore: Firestore): Promise { @@ -414,16 +414,16 @@ export function clearIndexedDbPersistence(firestore: Firestore): Promise { * Waits until all currently pending writes for the active user have been * acknowledged by the backend. * - * The returned Promise resolves immediately if there are no outstanding writes. - * Otherwise, the Promise waits for all previously issued writes (including + * The returned promise resolves immediately if there are no outstanding writes. + * Otherwise, the promise waits for all previously issued writes (including * those written in a previous app session), but it does not wait for writes * that were added after the function is called. If you want to wait for * additional writes, call `waitForPendingWrites()` again. * - * Any outstanding `waitForPendingWrites()` Promises are rejected during user + * Any outstanding `waitForPendingWrites()` promises are rejected during user * changes. * - * @returns A Promise which resolves when all currently pending writes have been + * @returns A `Promise` which resolves when all currently pending writes have been * acknowledged by the backend. */ export function waitForPendingWrites(firestore: Firestore): Promise { @@ -433,10 +433,10 @@ export function waitForPendingWrites(firestore: Firestore): Promise { } /** - * Re-enables use of the network for this Firestore instance after a prior + * Re-enables use of the network for this {@link Firestore} instance after a prior * call to {@link disableNetwork}. * - * @returns A promise that is resolved once the network has been enabled. + * @returns A `Promise` that is resolved once the network has been enabled. */ export function enableNetwork(firestore: Firestore): Promise { firestore = cast(firestore, Firestore); @@ -450,7 +450,7 @@ export function enableNetwork(firestore: Firestore): Promise { * `getDoc()` or `getDocs()` calls will return results from cache, and any write * operations will be queued until the network is restored. * - * @returns A promise that is resolved once the network has been disabled. + * @returns A `Promise` that is resolved once the network has been disabled. */ export function disableNetwork(firestore: Firestore): Promise { firestore = cast(firestore, Firestore); @@ -459,7 +459,7 @@ export function disableNetwork(firestore: Firestore): Promise { } /** - * Terminates the provided Firestore instance. + * Terminates the provided {@link Firestore} instance. * * After calling `terminate()` only the `clearIndexedDbPersistence()` function * may be used. Any other function will throw a `FirestoreError`. @@ -477,7 +477,7 @@ export function disableNetwork(firestore: Firestore): Promise { * of its resources or in combination with `clearIndexedDbPersistence()` to * ensure that all local state is destroyed between test runs. * - * @returns A promise that is resolved when the instance has been successfully + * @returns A `Promise` that is resolved when the instance has been successfully * terminated. */ export function terminate(firestore: Firestore): Promise { @@ -488,7 +488,7 @@ export function terminate(firestore: Firestore): Promise { /** * Loads a Firestore bundle into the local cache. * - * @param firestore - The `Firestore` instance to load bundles for for. + * @param firestore - The {@link Firestore} instance to load bundles for for. * @param bundleData - An object representing the bundle to be loaded. Valid objects are * `ArrayBuffer`, `ReadableStream` or `string`. * @@ -513,11 +513,11 @@ export function loadBundle( } /** - * Reads a Firestore `Query` from local cache, identified by the given name. + * Reads a Firestore {@link Query} from local cache, identified by the given name. * * The named queries are packaged into bundles on the server side (along * with resulting documents), and loaded to local cache using `loadBundle`. Once in local - * cache, use this method to extract a `Query` by name. + * cache, use this method to extract a {@link Query} by name. */ export function namedQuery( firestore: Firestore, diff --git a/packages/firestore/src/exp/reference_impl.ts b/packages/firestore/src/exp/reference_impl.ts index cf23286ceb7..e603a4ceacc 100644 --- a/packages/firestore/src/exp/reference_impl.ts +++ b/packages/firestore/src/exp/reference_impl.ts @@ -121,7 +121,7 @@ export class ExpUserDataWriter extends AbstractUserDataWriter { * Reads the document referred to by this `DocumentReference` from cache. * Returns an error if the document is not currently cached. * - * @returns A Promise resolved with a `DocumentSnapshot` containing the + * @returns A `Promise` resolved with a `DocumentSnapshot` containing the * current document contents. */ export function getDocFromCache( @@ -152,7 +152,7 @@ export function getDocFromCache( * Reads the document referred to by this `DocumentReference` from the server. * Returns an error if the network is not available. * - * @returns A Promise resolved with a `DocumentSnapshot` containing the + * @returns A `Promise` resolved with a `DocumentSnapshot` containing the * current document contents. */ export function getDocFromServer( @@ -175,7 +175,7 @@ export function getDocFromServer( * you are offline and the server cannot be reached. To specify this behavior, * invoke {@link getDocsFromCache} or {@link getDocsFromServer}. * - * @returns A Promise that will be resolved with the results of the query. + * @returns A `Promise` that will be resolved with the results of the query. */ export function getDocs(query: Query): Promise> { query = cast>(query, Query); @@ -196,7 +196,7 @@ export function getDocs(query: Query): Promise> { * Executes the query and returns the results as a `QuerySnapshot` from cache. * Returns an error if the document is not currently cached. * - * @returns A Promise that will be resolved with the results of the query. + * @returns A `Promise` that will be resolved with the results of the query. */ export function getDocsFromCache( query: Query @@ -215,7 +215,7 @@ export function getDocsFromCache( * Executes the query and returns the results as a `QuerySnapshot` from the * server. Returns an error if the network is not available. * - * @returns A Promise that will be resolved with the results of the query. + * @returns A `Promise` that will be resolved with the results of the query. */ export function getDocsFromServer( query: Query @@ -238,7 +238,7 @@ export function getDocsFromServer( * * @param reference - A reference to the document to write. * @param data - A map of the fields and values for the document. - * @returns A Promise resolved once the data has been successfully written + * @returns A `Promise` resolved once the data has been successfully written * to the backend (note that it won't resolve while you're offline). */ export function setDoc( @@ -297,7 +297,7 @@ export function setDoc( * @param data - An object containing the fields and values with which to * update the document. Fields can contain dots to reference nested fields * within the document. - * @returns A Promise resolved once the data has been successfully written + * @returns A `Promise` resolved once the data has been successfully written * to the backend (note that it won't resolve while you're offline). */ export function updateDoc( @@ -316,7 +316,7 @@ export function updateDoc( * @param field - The first field to update. * @param value - The first value. * @param moreFieldsAndValues - Additional key value pairs. - * @returns A Promise resolved once the data has been successfully written + * @returns A `Promise` resolved once the data has been successfully written * to the backend (note that it won't resolve while you're offline). */ export function updateDoc( @@ -387,7 +387,7 @@ export function deleteDoc( * * @param reference - A reference to the collection to add this document to. * @param data - An Object containing the data for the new document. - * @returns A Promise resolved with a `DocumentReference` pointing to the + * @returns A `Promise` resolved with a `DocumentReference` pointing to the * newly created document after it has been written to the backend (Note that it * won't resolve while you're offline). */ @@ -729,10 +729,10 @@ export function onSnapshotsInSync( * * NOTE: The snapshots-in-sync event only indicates that listeners are in sync * with each other, but does not relate to whether those snapshots are in sync - * with the server. Use SnapshotMetadata in the individual listeners to + * with the server. Use `SnapshotMetadata` in the individual listeners to * determine if a snapshot is from the cache or the server. * - * @param firestore - The instance of Firestore for synchronizing snapshots. + * @param firestore - The `Firestore` instance for synchronizing snapshots. * @param onSync - A callback to be called every time all snapshot listeners are * in sync with each other. * @returns An unsubscribe function that can be called to cancel the snapshot @@ -770,8 +770,8 @@ export function executeWrite( } /** - * Converts a ViewSnapshot that contains the single document specified by `ref` - * to a DocumentSnapshot. + * Converts a {@link ViewSnapshot} that contains the single document specified by `ref` + * to a {@link DocumentSnapshot}. */ function convertToDocSnapshot( firestore: Firestore, diff --git a/packages/firestore/src/exp/snapshot.ts b/packages/firestore/src/exp/snapshot.ts index b452436dac3..bc729e01dae 100644 --- a/packages/firestore/src/exp/snapshot.ts +++ b/packages/firestore/src/exp/snapshot.ts @@ -465,7 +465,7 @@ export class QuerySnapshot { } } -/** Calculates the array of DocumentChanges for a given ViewSnapshot. */ +/** Calculates the array of `DocumentChange`s for a given `ViewSnapshot`. */ export function changesFromSnapshot( querySnapshot: QuerySnapshot, includeMetadataChanges: boolean @@ -508,7 +508,7 @@ export function changesFromSnapshot( }; }); } else { - // A DocumentSet that is updated incrementally as changes are applied to use + // A `DocumentSet` that is updated incrementally as changes are applied to use // to lookup the index of a document. let indexTracker = querySnapshot._snapshot.oldDocs; return querySnapshot._snapshot.docChanges diff --git a/packages/firestore/src/exp/write_batch.ts b/packages/firestore/src/exp/write_batch.ts index 81efe0b57c5..09f91e36bb7 100644 --- a/packages/firestore/src/exp/write_batch.ts +++ b/packages/firestore/src/exp/write_batch.ts @@ -25,13 +25,13 @@ export { WriteBatch }; /** * Creates a write batch, used for performing multiple writes as a single - * atomic operation. The maximum number of writes allowed in a single WriteBatch + * atomic operation. The maximum number of writes allowed in a single {@link WriteBatch} * is 500. * * Unlike transactions, write batches are persisted offline and therefore are * preferable when you don't need to condition your writes on read data. * - * @returns A `WriteBatch` that can be used to atomically execute multiple + * @returns A {@link WriteBatch} that can be used to atomically execute multiple * writes. */ export function writeBatch(firestore: Firestore): WriteBatch { diff --git a/packages/firestore/src/lite/database.ts b/packages/firestore/src/lite/database.ts index 94c7f9f609c..536877fe672 100644 --- a/packages/firestore/src/lite/database.ts +++ b/packages/firestore/src/lite/database.ts @@ -147,7 +147,7 @@ export class Firestore implements FirestoreService { return this._terminateTask; } - /** Returns a JSON-serializable representation of this Firestore instance. */ + /** Returns a JSON-serializable representation of this `Firestore` instance. */ toJSON(): object { return { app: this._app, @@ -189,7 +189,7 @@ function databaseIdFromApp(app: FirebaseApp): DatabaseId { * @param app - The {@link @firebase/app#FirebaseApp} with which the `Firestore` instance will * be associated. * @param settings - A settings object to configure the `Firestore` instance. - * @returns A newly initialized Firestore instance. + * @returns A newly initialized `Firestore` instance. */ export function initializeFirestore( app: FirebaseApp, @@ -208,11 +208,11 @@ export function initializeFirestore( } /** - * Returns the existing instance of Firestore that is associated with the + * Returns the existing `Firestore` instance that is associated with the * provided {@link @firebase/app#FirebaseApp}. If no instance exists, initializes a new * instance with default settings. * - * @param app - The {@link @firebase/app#FirebaseApp} instance that the returned Firestore + * @param app - The {@link @firebase/app#FirebaseApp} instance that the returned `Firestore` * instance is associated with. * @returns The `Firestore` instance of the provided app. */ @@ -226,7 +226,7 @@ export function getFirestore(app: FirebaseApp = getApp()): Firestore { * Note: This must be called before this instance has been used to do any * operations. * - * @param firestore - The Firestore instance to configure to connect to the + * @param firestore - The `Firestore` instance to configure to connect to the * emulator. * @param host - the emulator host (ex: localhost). * @param port - the emulator port (ex: 9000). @@ -287,14 +287,14 @@ export function connectFirestoreEmulator( } /** - * Terminates the provided Firestore instance. + * Terminates the provided `Firestore` instance. * * After calling `terminate()` only the `clearIndexedDbPersistence()` functions * may be used. Any other function will throw a `FirestoreError`. Termination * does not cancel any pending writes, and any promises that are awaiting a * response from the server will not be resolved. * - * To restart after termination, create a new instance of FirebaseFirestore with + * To restart after termination, create a new instance of `Firestore` with * {@link getFirestore}. * * Note: Under normal circumstances, calling `terminate()` is not required. This @@ -302,8 +302,8 @@ export function connectFirestoreEmulator( * its resources or in combination with {@link clearIndexedDbPersistence} to * ensure that all local state is destroyed between test runs. * - * @param firestore - The Firestore instance to terminate. - * @returns A promise that is resolved when the instance has been successfully + * @param firestore - The `Firestore` instance to terminate. + * @returns A `Promise` that is resolved when the instance has been successfully * terminated. */ export function terminate(firestore: Firestore): Promise { diff --git a/packages/firestore/src/lite/field_path.ts b/packages/firestore/src/lite/field_path.ts index 24a0a36d65a..8e923dbe621 100644 --- a/packages/firestore/src/lite/field_path.ts +++ b/packages/firestore/src/lite/field_path.ts @@ -34,7 +34,7 @@ export class FieldPath { readonly _internalPath: InternalFieldPath; /** - * Creates a FieldPath from the provided field names. If more than one field + * Creates a `FieldPath` from the provided field names. If more than one field * name is provided, the path will point to a nested field in a document. * * @param fieldNames - A list of field names. diff --git a/packages/firestore/src/lite/query.ts b/packages/firestore/src/lite/query.ts index b0bc324a25d..59fce5b76ec 100644 --- a/packages/firestore/src/lite/query.ts +++ b/packages/firestore/src/lite/query.ts @@ -98,18 +98,18 @@ export abstract class QueryConstraint { abstract readonly type: QueryConstraintType; /** - * Takes the provided `Query` and returns a copy of the `Query` with this - * `QueryConstraint` applied. + * Takes the provided {@link Query} and returns a copy of the {@link Query} with this + * {@link QueryConstraint} applied. */ abstract _apply(query: Query): Query; } /** - * Creates a new immutable instance of `Query` that is extended to also include + * Creates a new immutable instance of {@link Query} that is extended to also include * additional query constraints. * - * @param query - The Query instance to use as a base for the new constraints. - * @param queryConstraints - The list of `QueryConstraint`s to apply. + * @param query - The {@link Query} instance to use as a base for the new constraints. + * @param queryConstraints - The list of {@link QueryConstraint}s to apply. * @throws if any of the provided query constraints cannot be combined with the * existing or new constraints. */ @@ -171,7 +171,7 @@ export type WhereFilterOp = | 'not-in'; /** - * Creates a `QueryConstraint` that enforces that documents must contain the + * Creates a {@link QueryConstraint} that enforces that documents must contain the * specified field and that the value should satisfy the relation constraint * provided. * @@ -179,7 +179,7 @@ export type WhereFilterOp = * @param opStr - The operation string (e.g "<", "<=", "==", "<", * "<=", "!="). * @param value - The value for comparison - * @returns The created `Query`. + * @returns The created {@link Query}. */ export function where( fieldPath: string | FieldPath, @@ -218,13 +218,13 @@ class QueryOrderByConstraint extends QueryConstraint { export type OrderByDirection = 'desc' | 'asc'; /** - * Creates a `QueryConstraint` that sorts the query result by the + * Creates a {@link QueryConstraint} that sorts the query result by the * specified field, optionally in descending order instead of ascending. * * @param fieldPath - The field to sort by. * @param directionStr - Optional direction to sort by ('asc' or 'desc'). If * not specified, order will be ascending. - * @returns The created `Query`. + * @returns The created {@link Query}. */ export function orderBy( fieldPath: string | FieldPath, @@ -254,10 +254,10 @@ class QueryLimitConstraint extends QueryConstraint { } /** - * Creates a `QueryConstraint` that only returns the first matching documents. + * Creates a {@link QueryConstraint} that only returns the first matching documents. * * @param limit - The maximum number of items to return. - * @returns The created `Query`. + * @returns The created {@link Query}. */ export function limit(limit: number): QueryConstraint { validatePositiveNumber('limit', limit); @@ -265,13 +265,13 @@ export function limit(limit: number): QueryConstraint { } /** - * Creates a `QueryConstraint` that only returns the last matching documents. + * Creates a {@link QueryConstraint} that only returns the last matching documents. * * You must specify at least one `orderBy` clause for `limitToLast` queries, * otherwise an exception will be thrown during execution. * * @param limit - The maximum number of items to return. - * @returns The created `Query`. + * @returns The created {@link Query}. */ export function limitToLast(limit: number): QueryConstraint { validatePositiveNumber('limitToLast', limit); @@ -303,23 +303,23 @@ class QueryStartAtConstraint extends QueryConstraint { } /** - * Creates a `QueryConstraint` that modifies the result set to start at the + * Creates a {@link QueryConstraint} that modifies the result set to start at the * provided document (inclusive). The starting position is relative to the order * of the query. The document must contain all of the fields provided in the * `orderBy` of this query. * * @param snapshot - The snapshot of the document to start at. - * @returns A `QueryConstraint` to pass to `query()`. + * @returns A {@link QueryConstraint} to pass to `query()`. */ export function startAt(snapshot: DocumentSnapshot): QueryConstraint; /** - * Creates a `QueryConstraint` that modifies the result set to start at the + * Creates a {@link QueryConstraint} that modifies the result set to start at the * provided fields relative to the order of the query. The order of the field * values must match the order of the order by clauses of the query. * * @param fieldValues - The field values to start this query at, in order * of the query's order by. - * @returns A `QueryConstraint` to pass to `query()`. + * @returns A {@link QueryConstraint} to pass to `query()`. */ export function startAt(...fieldValues: unknown[]): QueryConstraint; export function startAt( @@ -329,25 +329,25 @@ export function startAt( } /** - * Creates a `QueryConstraint` that modifies the result set to start after the + * Creates a {@link QueryConstraint} that modifies the result set to start after the * provided document (exclusive). The starting position is relative to the order * of the query. The document must contain all of the fields provided in the * orderBy of the query. * * @param snapshot - The snapshot of the document to start after. - * @returns A `QueryConstraint` to pass to `query()` + * @returns A {@link QueryConstraint} to pass to `query()` */ export function startAfter( snapshot: DocumentSnapshot ): QueryConstraint; /** - * Creates a `QueryConstraint` that modifies the result set to start after the + * Creates a {@link QueryConstraint} that modifies the result set to start after the * provided fields relative to the order of the query. The order of the field * values must match the order of the order by clauses of the query. * * @param fieldValues - The field values to start this query after, in order * of the query's order by. - * @returns A `QueryConstraint` to pass to `query()` + * @returns A {@link QueryConstraint} to pass to `query()` */ export function startAfter(...fieldValues: unknown[]): QueryConstraint; export function startAfter( @@ -385,23 +385,23 @@ class QueryEndAtConstraint extends QueryConstraint { } /** - * Creates a `QueryConstraint` that modifies the result set to end before the + * Creates a {@link QueryConstraint} that modifies the result set to end before the * provided document (exclusive). The end position is relative to the order of * the query. The document must contain all of the fields provided in the * orderBy of the query. * * @param snapshot - The snapshot of the document to end before. - * @returns A `QueryConstraint` to pass to `query()` + * @returns A {@link QueryConstraint} to pass to `query()` */ export function endBefore(snapshot: DocumentSnapshot): QueryConstraint; /** - * Creates a `QueryConstraint` that modifies the result set to end before the + * Creates a {@link QueryConstraint} that modifies the result set to end before the * provided fields relative to the order of the query. The order of the field * values must match the order of the order by clauses of the query. * * @param fieldValues - The field values to end this query before, in order * of the query's order by. - * @returns A `QueryConstraint` to pass to `query()` + * @returns A {@link QueryConstraint} to pass to `query()` */ export function endBefore(...fieldValues: unknown[]): QueryConstraint; export function endBefore( @@ -411,23 +411,23 @@ export function endBefore( } /** - * Creates a `QueryConstraint` that modifies the result set to end at the + * Creates a {@link QueryConstraint} that modifies the result set to end at the * provided document (inclusive). The end position is relative to the order of * the query. The document must contain all of the fields provided in the * orderBy of the query. * * @param snapshot - The snapshot of the document to end at. - * @returns A `QueryConstraint` to pass to `query()` + * @returns A {@link QueryConstraint} to pass to `query()` */ export function endAt(snapshot: DocumentSnapshot): QueryConstraint; /** - * Creates a `QueryConstraint` that modifies the result set to end at the + * Creates a {@link QueryConstraint} that modifies the result set to end at the * provided fields relative to the order of the query. The order of the field * values must match the order of the order by clauses of the query. * * @param fieldValues - The field values to end this query at, in order * of the query's order by. - * @returns A `QueryConstraint` to pass to `query()` + * @returns A {@link QueryConstraint} to pass to `query()` */ export function endAt(...fieldValues: unknown[]): QueryConstraint; export function endAt( @@ -538,9 +538,9 @@ export function newQueryOrderBy( } /** - * Create a Bound from a query and a document. + * Create a `Bound` from a query and a document. * - * Note that the Bound will always include the key of the document + * Note that the `Bound` will always include the key of the document * and so only the provided document will compare equal to the returned * position. * @@ -603,7 +603,7 @@ export function newQueryBoundFromDocument( } /** - * Converts a list of field values to a Bound for the given query. + * Converts a list of field values to a `Bound` for the given query. */ export function newQueryBoundFromFields( query: InternalQuery, @@ -666,9 +666,9 @@ export function newQueryBoundFromFields( } /** - * Parses the given documentIdValue into a ReferenceValue, throwing - * appropriate errors if the value is anything other than a DocumentReference - * or String, or if the string is malformed. + * Parses the given `documentIdValue` into a `ReferenceValue`, throwing + * appropriate errors if the value is anything other than a `DocumentReference` + * or `string`, or if the string is malformed. */ function parseDocumentIdValue( databaseId: DatabaseId, @@ -745,11 +745,11 @@ function validateDisjunctiveFilterElements( * Operators in a query must adhere to the following set of rules: * 1. Only one array operator is allowed. * 2. Only one disjunctive operator is allowed. - * 3. NOT_EQUAL cannot be used with another NOT_EQUAL operator. - * 4. NOT_IN cannot be used with array, disjunctive, or NOT_EQUAL operators. + * 3. `NOT_EQUAL` cannot be used with another `NOT_EQUAL` operator. + * 4. `NOT_IN` cannot be used with array, disjunctive, or `NOT_EQUAL` operators. * - * Array operators: ARRAY_CONTAINS, ARRAY_CONTAINS_ANY - * Disjunctive operators: IN, ARRAY_CONTAINS_ANY, NOT_IN + * Array operators: `ARRAY_CONTAINS`, `ARRAY_CONTAINS_ANY` + * Disjunctive operators: `IN`, `ARRAY_CONTAINS_ANY`, `NOT_IN` */ function conflictingOps(op: Operator): Operator[] { switch (op) { diff --git a/packages/firestore/src/lite/reference.ts b/packages/firestore/src/lite/reference.ts index 68738982b72..046773041c6 100644 --- a/packages/firestore/src/lite/reference.ts +++ b/packages/firestore/src/lite/reference.ts @@ -90,7 +90,7 @@ export class DocumentReference { readonly type = 'document'; /** - * The {@link FirebaseFirestore} the document is in. + * The {@link Firestore} instance the document is in. * This is useful for performing transactions, for example. */ readonly firestore: Firestore; @@ -163,7 +163,7 @@ export class DocumentReference { } /** - * A `Query` refers to a Query which you can read or listen to. You can also + * A `Query` refers to a query which you can read or listen to. You can also * construct refined `Query` objects by adding filters and ordering. */ export class Query { @@ -171,7 +171,7 @@ export class Query { readonly type: 'query' | 'collection' = 'query'; /** - * The `FirebaseFirestore` for the Firestore database (useful for performing + * The `Firestore` instance for the Firestore database (useful for performing * transactions, etc.). */ readonly firestore: Firestore; @@ -260,7 +260,7 @@ export class CollectionReference extends Query { } /** - * Applies a custom data converter to this CollectionReference, allowing you + * Applies a custom data converter to this `CollectionReference`, allowing you * to use your own custom model objects with Firestore. When you call {@link * addDoc} with the returned `CollectionReference` instance, the provided * converter will convert between Firestore data and your custom type `U`. @@ -290,7 +290,7 @@ export class CollectionReference extends Query { * Gets a `CollectionReference` instance that refers to the collection at * the specified absolute path. * - * @param firestore - A reference to the root Firestore instance. + * @param firestore - A reference to the root `Firestore` instance. * @param path - A slash-separated path to a collection. * @param pathSegments - Additional path segments to apply relative to the first * argument. @@ -381,7 +381,7 @@ export function collection( * database that are contained in a collection or subcollection with the * given `collectionId`. * - * @param firestore - A reference to the root Firestore instance. + * @param firestore - A reference to the root `Firestore` instance. * @param collectionId - Identifies the collections to query over. Every * collection or subcollection with this ID as the last segment of its path * will be included. Cannot contain a slash. @@ -411,9 +411,9 @@ export function collectionGroup( /** * Gets a `DocumentReference` instance that refers to the document at the - * specified abosulute path. + * specified absolute path. * - * @param firestore - A reference to the root Firestore instance. + * @param firestore - A reference to the root `Firestore` instance. * @param path - A slash-separated path to a document. * @param pathSegments - Additional path segments that will be applied relative * to the first argument. diff --git a/packages/firestore/src/lite/reference_impl.ts b/packages/firestore/src/lite/reference_impl.ts index fdbd0bc9774..aa9c1687d3c 100644 --- a/packages/firestore/src/lite/reference_impl.ts +++ b/packages/firestore/src/lite/reference_impl.ts @@ -61,12 +61,12 @@ import { import { AbstractUserDataWriter } from './user_data_writer'; /** - * Converts custom model object of type T into DocumentData by applying the + * Converts custom model object of type T into `DocumentData` by applying the * converter if it exists. * - * This function is used when converting user objects to DocumentData + * This function is used when converting user objects to `DocumentData` * because we want to provide the user with a more specific error message if - * their set() or fails due to invalid data originating from a toFirestore() + * their `set()` or fails due to invalid data originating from a `toFirestore()` * call. */ export function applyFirestoreDataConverter( @@ -186,13 +186,13 @@ export function getDocs(query: Query): Promise> { * the document does not yet exist, it will be created. * * The result of this write will only be reflected in document reads that occur - * after the returned Promise resolves. If the client is offline, the + * after the returned promise resolves. If the client is offline, the * write fails. If you would like to see local modifications or buffer writes * until the client is online, use the full Firestore SDK. * * @param reference - A reference to the document to write. * @param data - A map of the fields and values for the document. - * @returns A Promise resolved once the data has been successfully written + * @returns A `Promise` resolved once the data has been successfully written * to the backend. */ export function setDoc( @@ -205,14 +205,14 @@ export function setDoc( * or `mergeFields`, the provided data can be merged into an existing document. * * The result of this write will only be reflected in document reads that occur - * after the returned Promise resolves. If the client is offline, the + * after the returned promise resolves. If the client is offline, the * write fails. If you would like to see local modifications or buffer writes * until the client is online, use the full Firestore SDK. * * @param reference - A reference to the document to write. * @param data - A map of the fields and values for the document. * @param options - An object to configure the set behavior. - * @returns A Promise resolved once the data has been successfully written + * @returns A `Promise` resolved once the data has been successfully written * to the backend. */ export function setDoc( @@ -253,7 +253,7 @@ export function setDoc( * not exist. * * The result of this update will only be reflected in document reads that occur - * after the returned Promise resolves. If the client is offline, the + * after the returned promise resolves. If the client is offline, the * update fails. If you would like to see local modifications or buffer writes * until the client is online, use the full Firestore SDK. * @@ -261,7 +261,7 @@ export function setDoc( * @param data - An object containing the fields and values with which to * update the document. Fields can contain dots to reference nested fields * within the document. - * @returns A Promise resolved once the data has been successfully written + * @returns A `Promise` resolved once the data has been successfully written * to the backend. */ export function updateDoc( @@ -277,7 +277,7 @@ export function updateDoc( * strings or by providing `FieldPath` objects. * * The result of this update will only be reflected in document reads that occur - * after the returned Promise resolves. If the client is offline, the + * after the returned promise resolves. If the client is offline, the * update fails. If you would like to see local modifications or buffer writes * until the client is online, use the full Firestore SDK. * @@ -285,7 +285,7 @@ export function updateDoc( * @param field - The first field to update. * @param value - The first value. * @param moreFieldsAndValues - Additional key value pairs. - * @returns A Promise resolved once the data has been successfully written + * @returns A `Promise` resolved once the data has been successfully written * to the backend. */ export function updateDoc( @@ -339,12 +339,12 @@ export function updateDoc( * Deletes the document referred to by the specified `DocumentReference`. * * The deletion will only be reflected in document reads that occur after the - * returned Promise resolves. If the client is offline, the + * returned promise resolves. If the client is offline, the * delete fails. If you would like to see local modifications or buffer writes * until the client is online, use the full Firestore SDK. * * @param reference - A reference to the document to delete. - * @returns A Promise resolved once the document has been successfully + * @returns A `Promise` resolved once the document has been successfully * deleted from the backend. */ export function deleteDoc( @@ -362,13 +362,13 @@ export function deleteDoc( * assigning it a document ID automatically. * * The result of this write will only be reflected in document reads that occur - * after the returned Promise resolves. If the client is offline, the + * after the returned promise resolves. If the client is offline, the * write fails. If you would like to see local modifications or buffer writes * until the client is online, use the full Firestore SDK. * * @param reference - A reference to the collection to add this document to. * @param data - An Object containing the data for the new document. - * @returns A Promise resolved with a `DocumentReference` pointing to the + * @returns A `Promise` resolved with a `DocumentReference` pointing to the * newly created document after it has been written to the backend. */ export function addDoc( diff --git a/packages/firestore/src/lite/settings.ts b/packages/firestore/src/lite/settings.ts index acbf55648eb..3743cc344d0 100644 --- a/packages/firestore/src/lite/settings.ts +++ b/packages/firestore/src/lite/settings.ts @@ -64,7 +64,7 @@ export interface PrivateSettings extends FirestoreSettings { /** * A concrete type describing all the values that can be applied via a - * user-supplied firestore.Settings object. This is a separate type so that + * user-supplied `FirestoreSettings` object. This is a separate type so that * defaults can be supplied and the value can be checked for equality. */ export class FirestoreSettingsImpl { diff --git a/packages/firestore/src/lite/snapshot.ts b/packages/firestore/src/lite/snapshot.ts index b0a08ba8850..725f994df5d 100644 --- a/packages/firestore/src/lite/snapshot.ts +++ b/packages/firestore/src/lite/snapshot.ts @@ -313,7 +313,7 @@ export function snapshotEqual( } /** - * Helper that calls fromDotSeparatedString() but wraps any error thrown. + * Helper that calls `fromDotSeparatedString()` but wraps any error thrown. */ export function fieldPathFromArgument( methodName: string, diff --git a/packages/firestore/src/lite/timestamp.ts b/packages/firestore/src/lite/timestamp.ts index 6a678e2cc46..f0b3104891e 100644 --- a/packages/firestore/src/lite/timestamp.ts +++ b/packages/firestore/src/lite/timestamp.ts @@ -163,7 +163,7 @@ export class Timestamp { ); } - /** Returns a textual representation of this Timestamp. */ + /** Returns a textual representation of this `Timestamp`. */ toString(): string { return ( 'Timestamp(seconds=' + @@ -174,13 +174,13 @@ export class Timestamp { ); } - /** Returns a JSON-serializable representation of this Timestamp. */ + /** Returns a JSON-serializable representation of this `Timestamp`. */ toJSON(): { seconds: number; nanoseconds: number } { return { seconds: this.seconds, nanoseconds: this.nanoseconds }; } /** - * Converts this object to a primitive string, which allows Timestamp objects + * Converts this object to a primitive string, which allows `Timestamp` objects * to be compared using the `>`, `<=`, `>=` and `>` operators. */ valueOf(): string { diff --git a/packages/firestore/src/lite/write_batch.ts b/packages/firestore/src/lite/write_batch.ts index ce1f786c8e2..ea73fb18eb4 100644 --- a/packages/firestore/src/lite/write_batch.ts +++ b/packages/firestore/src/lite/write_batch.ts @@ -201,11 +201,11 @@ export class WriteBatch { * Commits all of the writes in this write batch as a single atomic unit. * * The result of these writes will only be reflected in document reads that - * occur after the returned Promise resolves. If the client is offline, the + * occur after the returned promise resolves. If the client is offline, the * write fails. If you would like to see local modifications or buffer writes * until the client is online, use the full Firestore SDK. * - * @returns A Promise resolved once all of the writes in the batch have been + * @returns A `Promise` resolved once all of the writes in the batch have been * successfully written to the backend as an atomic unit (note that it won't * resolve while you're offline). */ @@ -252,7 +252,7 @@ export function validateReference( * is 500. * * The result of these writes will only be reflected in document reads that - * occur after the returned Promise resolves. If the client is offline, the + * occur after the returned promise resolves. If the client is offline, the * write fails. If you would like to see local modifications or buffer writes * until the client is online, use the full Firestore SDK. * diff --git a/packages/firestore/src/local/persistence.ts b/packages/firestore/src/local/persistence.ts index 2cbdfbae9ee..c650196901d 100644 --- a/packages/firestore/src/local/persistence.ts +++ b/packages/firestore/src/local/persistence.ts @@ -235,7 +235,7 @@ export interface Persistence { * be acquired and the returned promise will be rejected with a * FAILED_PRECONDITION error. * @param transactionOperation - The operation to run inside a transaction. - * @returns A promise that is resolved once the transaction completes. + * @returns A `Promise` that is resolved once the transaction completes. */ runTransaction( action: string, diff --git a/packages/firestore/src/local/simple_db.ts b/packages/firestore/src/local/simple_db.ts index 611f6fc9996..7ec99397368 100644 --- a/packages/firestore/src/local/simple_db.ts +++ b/packages/firestore/src/local/simple_db.ts @@ -55,7 +55,7 @@ export class SimpleDbTransaction { private aborted = false; /** - * A promise that resolves with the result of the IndexedDb transaction. + * A `Promise` that resolves with the result of the IndexedDb transaction. */ private readonly completionDeferred = new Deferred(); diff --git a/packages/storage/compat/reference.ts b/packages/storage/compat/reference.ts index 29deef4efcf..d882642d6bf 100644 --- a/packages/storage/compat/reference.ts +++ b/packages/storage/compat/reference.ts @@ -43,7 +43,8 @@ import { invalidRootOperation } from '../src/implementation/error'; import { Compat } from '@firebase/util'; export class ReferenceCompat - implements types.Reference, Compat { + implements types.Reference, Compat +{ constructor( readonly _delegate: StorageReference, public storage: StorageServiceCompat @@ -185,7 +186,7 @@ export class ReferenceCompat } /** - * A promise that resolves with the metadata for this object. If this + * A `Promise` that resolves with the metadata for this object. If this * object doesn't exist or metadata cannot be retreived, the promise is * rejected. */ @@ -198,7 +199,7 @@ export class ReferenceCompat * @param metadata - The new metadata for the object. * Only values that have been explicitly set will be changed. Explicitly * setting a value to null will remove the metadata. - * @returns A promise that resolves + * @returns A `Promise` that resolves * with the new metadata for this object. * @see firebaseStorage.Reference.prototype.getMetadata */ @@ -212,7 +213,7 @@ export class ReferenceCompat } /** - * @returns A promise that resolves with the download + * @returns A `Promise` that resolves with the download * URL for this object. */ getDownloadURL(): Promise { @@ -221,7 +222,7 @@ export class ReferenceCompat /** * Deletes the object at this location. - * @returns A promise that resolves if the deletion succeeds. + * @returns A `Promise` that resolves if the deletion succeeds. */ delete(): Promise { this._throwIfRoot('delete'); diff --git a/packages/storage/exp/api.ts b/packages/storage/exp/api.ts index 80f067fa2f2..171d7641e19 100644 --- a/packages/storage/exp/api.ts +++ b/packages/storage/exp/api.ts @@ -132,11 +132,11 @@ export function uploadBytesResumable( } /** - * A promise that resolves with the metadata for this object. If this + * A `Promise` that resolves with the metadata for this object. If this * object doesn't exist or metadata cannot be retreived, the promise is * rejected. * @public - * @param ref - StorageReference to get metadata from. + * @param ref - {@link StorageReference} to get metadata from. */ export function getMetadata(ref: StorageReference): Promise { ref = getModularInstance(ref); @@ -146,11 +146,11 @@ export function getMetadata(ref: StorageReference): Promise { /** * Updates the metadata for this object. * @public - * @param ref - StorageReference to update metadata for. + * @param ref - {@link StorageReference} to update metadata for. * @param metadata - The new metadata for the object. * Only values that have been explicitly set will be changed. Explicitly * setting a value to null will remove the metadata. - * @returns A promise that resolves with the new metadata for this object. + * @returns A `Promise` that resolves with the new metadata for this object. */ export function updateMetadata( ref: StorageReference, @@ -178,9 +178,9 @@ export function updateMetadata( * list() may fail if there are too many unsupported objects in the bucket. * @public * - * @param ref - StorageReference to get list from. - * @param options - See ListOptions for details. - * @returns A Promise that resolves with the items and prefixes. + * @param ref - {@link StorageReference} to get list from. + * @param options - See {@link ListOptions} for details. + * @returns A `Promise` that resolves with the items and prefixes. * `prefixes` contains references to sub-folders and `items` * contains references to objects in this folder. `nextPageToken` * can be used to get the rest of the results. @@ -202,12 +202,12 @@ export function list( * Note: The results may not be consistent if objects are changed while this * operation is running. * - * Warning: listAll may potentially consume too many resources if there are + * Warning: `listAll` may potentially consume too many resources if there are * too many results. * @public - * @param ref - StorageReference to get list from. + * @param ref - {@link StorageReference} to get list from. * - * @returns A Promise that resolves with all the items and prefixes under + * @returns A `Promise` that resolves with all the items and prefixes under * the current storage reference. `prefixes` contains references to * sub-directories and `items` contains references to objects in this * folder. `nextPageToken` is never returned. @@ -218,9 +218,10 @@ export function listAll(ref: StorageReference): Promise { } /** - * Returns the download URL for the given Reference. + * Returns the download URL for the given {@link StorageReference}. * @public - * @returns A promise that resolves with the download + * @param ref - {@link StorageReference} to get the download URL for. + * @returns A `Promise` that resolves with the download * URL for this object. */ export function getDownloadURL(ref: StorageReference): Promise { @@ -231,8 +232,8 @@ export function getDownloadURL(ref: StorageReference): Promise { /** * Deletes the object at this location. * @public - * @param ref - StorageReference for object to delete. - * @returns A promise that resolves if the deletion succeeds. + * @param ref - {@link StorageReference} for object to delete. + * @returns A `Promise` that resolves if the deletion succeeds. */ export function deleteObject(ref: StorageReference): Promise { ref = getModularInstance(ref); @@ -240,18 +241,18 @@ export function deleteObject(ref: StorageReference): Promise { } /** - * Returns a StorageReference for the given url. - * @param storage - `StorageService` instance. + * Returns a {@link StorageReference} for the given url. + * @param storage - {@link FirebaseStorage} instance. * @param url - URL. If empty, returns root reference. * @public */ export function ref(storage: FirebaseStorage, url?: string): StorageReference; /** - * Returns a StorageReference for the given path in the + * Returns a {@link StorageReference} for the given path in the * default bucket. - * @param storageOrRef - `StorageService` or `StorageReference`. - * @param pathOrUrlStorage - path. If empty, returns root reference (if Storage - * instance provided) or returns same reference (if Reference provided). + * @param storageOrRef - {@link FirebaseStorage} or {@link StorageReference}. + * @param pathOrUrlStorage - path. If empty, returns root reference (if {@link FirebaseStorage} + * instance provided) or returns same reference (if {@link StorageReference} provided). * @public */ export function ref( @@ -279,12 +280,12 @@ export function _getChild(ref: StorageReference, childPath: string): Reference { export { StringFormat } from '../src/implementation/string'; /** - * Gets a Firebase StorageService instance for the given Firebase app. + * Gets a {@link FirebaseStorage} instance for the given Firebase app. * @public - * @param app - Firebase app to get Storage instance for. + * @param app - Firebase app to get {@link FirebaseStorage} instance for. * @param bucketUrl - The gs:// url to your Firebase Storage Bucket. * If not passed, uses the app's default Storage Bucket. - * @returns A Firebase StorageService instance. + * @returns A {@link FirebaseStorage} instance. */ export function getStorage( app: FirebaseApp = getApp(), @@ -302,9 +303,9 @@ export function getStorage( } /** - * Modify this `StorageService` instance to communicate with the Cloud Storage emulator. + * Modify this {@link FirebaseStorage} instance to communicate with the Cloud Storage emulator. * - * @param storage - The `StorageService` instance + * @param storage - The {@link FirebaseStorage} instance * @param host - The emulator host (ex: localhost) * @param port - The emulator port (ex: 5001) * @param options.mockUserToken - the mock auth token to use for unit testing Security Rules. diff --git a/packages/storage/exp/public-types.ts b/packages/storage/exp/public-types.ts index d982f61805f..210e096d23e 100644 --- a/packages/storage/exp/public-types.ts +++ b/packages/storage/exp/public-types.ts @@ -76,7 +76,7 @@ export interface StorageReference { */ name: string; /** - * The StorageService associated with this reference. + * The {@link FirebaseStorage} instance associated with this reference. */ storage: FirebaseStorage; /** diff --git a/packages/storage/src/reference.ts b/packages/storage/src/reference.ts index 944af2c0577..cd237acd80c 100644 --- a/packages/storage/src/reference.ts +++ b/packages/storage/src/reference.ts @@ -317,7 +317,7 @@ export async function list( } /** - * A promise that resolves with the metadata for this object. If this + * A `Promise` that resolves with the metadata for this object. If this * object doesn't exist or metadata cannot be retreived, the promise is * rejected. * @public @@ -340,7 +340,7 @@ export async function getMetadata(ref: Reference): Promise { * @param metadata - The new metadata for the object. * Only values that have been explicitly set will be changed. Explicitly * setting a value to null will remove the metadata. - * @returns A promise that resolves + * @returns A `Promise` that resolves * with the new metadata for this object. * See `firebaseStorage.Reference.prototype.getMetadata` */ @@ -361,7 +361,7 @@ export async function updateMetadata( /** * Returns the download URL for the given Reference. * @public - * @returns A promise that resolves with the download + * @returns A `Promise` that resolves with the download * URL for this object. */ export async function getDownloadURL(ref: Reference): Promise { @@ -385,7 +385,7 @@ export async function getDownloadURL(ref: Reference): Promise { * Deletes the object at this location. * @public * @param ref - StorageReference for object to delete. - * @returns A promise that resolves if the deletion succeeds. + * @returns A `Promise` that resolves if the deletion succeeds. */ export async function deleteObject(ref: Reference): Promise { ref._throwIfRoot('deleteObject');