diff --git a/etc/firebase-admin.messaging.api.md b/etc/firebase-admin.messaging.api.md index 361a44b70e..9b6416aa0d 100644 --- a/etc/firebase-admin.messaging.api.md +++ b/etc/firebase-admin.messaging.api.md @@ -180,7 +180,6 @@ export type Message = TokenMessage | TopicMessage | ConditionMessage; // @public export class Messaging { - constructor(app: App); get app(): App; send(message: Message, dryRun?: boolean): Promise; sendAll(messages: Message[], dryRun?: boolean): Promise; diff --git a/src/app/core.ts b/src/app/core.ts index a946e8ab41..9434ab6244 100644 --- a/src/app/core.ts +++ b/src/app/core.ts @@ -20,7 +20,7 @@ import { Agent } from 'http'; import { Credential } from './credential'; /** - * Available options to pass to [`initializeApp()`](admin#.initializeApp). + * Available options to pass to {@link firebase-admin.app#initializeApp}. */ export interface AppOptions { @@ -28,13 +28,13 @@ export interface AppOptions { * A {@link Credential `Credential`} object used to * authenticate the Admin SDK. * - * See [Initialize the SDK](/docs/admin/setup#initialize_the_sdk) for detailed - * documentation and code samples. + * See {@link https://firebase.google.com/docs/admin/setup#initialize_the_sdk | Initialize the SDK} + * for detailed documentation and code samples. */ credential?: Credential; /** - * The object to use as the [`auth`](/docs/reference/security/database/#auth) + * The object to use as the {@link https://firebase.google.com/docs/reference/security/database/#auth | auth} * variable in your Realtime Database Rules when the Admin SDK reads from or * writes to the Realtime Database. This allows you to downscope the Admin SDK * from its default full read and write privileges. @@ -42,7 +42,8 @@ export interface AppOptions { * You can pass `null` to act as an unauthenticated client. * * See - * [Authenticate with limited privileges](/docs/database/admin/start#authenticate-with-limited-privileges) + * {@link https://firebase.google.com/docs/database/admin/start#authenticate-with-limited-privileges | + * Authenticate with limited privileges} * for detailed documentation and code samples. */ databaseAuthVariableOverride?: object | null; @@ -71,7 +72,7 @@ export interface AppOptions { projectId?: string; /** - * An [HTTP Agent](https://nodejs.org/api/http.html#http_class_http_agent) + * An {@link https://nodejs.org/api/http.html#http_class_http_agent | HTTP Agent} * to be used when making outgoing HTTP calls. This Agent instance is used * by all services that make REST calls (e.g. `auth`, `messaging`, * `projectManagement`). @@ -87,12 +88,6 @@ export interface AppOptions { /** * A Firebase app holds the initialization information for a collection of * services. - * - * Do not call this constructor directly. Instead, use - * {@link - * https://firebase.google.com/docs/reference/admin/node/admin#.initializeApp - * `admin.initializeApp()`} - * to create an app. */ export interface App { @@ -119,10 +114,7 @@ export interface App { /** * The (read-only) configuration options for this app. These are the original - * parameters given in - * {@link - * https://firebase.google.com/docs/reference/admin/node/admin#.initializeApp - * `admin.initializeApp()`}. + * parameters given in {@link firebase-admin.app#initializeApp}. * * @example * ```javascript @@ -170,7 +162,9 @@ export interface FirebaseError { stack?: string; /** - * @return A JSON-serializable representation of this object. + * Returns a JSON-serializable object representation of this error. + * + * @returns A JSON-serializable representation of this object. */ toJSON(): object; } diff --git a/src/app/credential-factory.ts b/src/app/credential-factory.ts index 96f92821f8..4ad5ea5cf9 100644 --- a/src/app/credential-factory.ts +++ b/src/app/credential-factory.ts @@ -28,22 +28,16 @@ const globalRefreshTokenCreds: { [key: string]: RefreshTokenCredential } = {}; /** * Returns a credential created from the - * {@link - * https://developers.google.com/identity/protocols/application-default-credentials - * Google Application Default Credentials} + * {@link https://developers.google.com/identity/protocols/application-default-credentials | + * Google Application Default Credentials} * that grants admin access to Firebase services. This credential can be used - * in the call to - * {@link - * https://firebase.google.com/docs/reference/admin/node/admin#.initializeApp - * `admin.initializeApp()`}. + * in the call to {@link firebase-admin.app#initializeApp}. * * Google Application Default Credentials are available on any Google * infrastructure, such as Google App Engine and Google Compute Engine. * * See - * {@link - * https://firebase.google.com/docs/admin/setup#initialize_the_sdk - * Initialize the SDK} + * {@link https://firebase.google.com/docs/admin/setup#initialize_the_sdk | Initialize the SDK} * for more details. * * @example @@ -54,10 +48,10 @@ const globalRefreshTokenCreds: { [key: string]: RefreshTokenCredential } = {}; * }); * ``` * - * @param httpAgent Optional [HTTP Agent](https://nodejs.org/api/http.html#http_class_http_agent) + * @param httpAgent Optional {@link https://nodejs.org/api/http.html#http_class_http_agent | HTTP Agent} * to be used when retrieving access tokens from Google token servers. * - * @return A credential authenticated via Google + * @returns A credential authenticated via Google * Application Default Credentials that can be used to initialize an app. */ export function applicationDefault(httpAgent?: Agent): Credential { @@ -70,15 +64,10 @@ export function applicationDefault(httpAgent?: Agent): Credential { /** * Returns a credential created from the provided service account that grants * admin access to Firebase services. This credential can be used in the call - * to - * {@link - * https://firebase.google.com/docs/reference/admin/node/admin#.initializeApp - * `admin.initializeApp()`}. + * to {@link firebase-admin.app#initializeApp}. * * See - * {@link - * https://firebase.google.com/docs/admin/setup#initialize_the_sdk - * Initialize the SDK} + * {@link https://firebase.google.com/docs/admin/setup#initialize_the_sdk | Initialize the SDK} * for more details. * * @example @@ -106,10 +95,10 @@ export function applicationDefault(httpAgent?: Agent): Credential { * * @param serviceAccountPathOrObject The path to a service * account key JSON file or an object representing a service account key. - * @param httpAgent Optional [HTTP Agent](https://nodejs.org/api/http.html#http_class_http_agent) + * @param httpAgent Optional {@link https://nodejs.org/api/http.html#http_class_http_agent | HTTP Agent} * to be used when retrieving access tokens from Google token servers. * - * @return A credential authenticated via the + * @returns A credential authenticated via the * provided service account that can be used to initialize an app. */ export function cert(serviceAccountPathOrObject: string | ServiceAccount, httpAgent?: Agent): Credential { @@ -124,15 +113,10 @@ export function cert(serviceAccountPathOrObject: string | ServiceAccount, httpAg /** * Returns a credential created from the provided refresh token that grants * admin access to Firebase services. This credential can be used in the call - * to - * {@link - * https://firebase.google.com/docs/reference/admin/node/admin#.initializeApp - * `admin.initializeApp()`}. + * to {@link firebase-admin.app#initializeApp}. * * See - * {@link - * https://firebase.google.com/docs/admin/setup#initialize_the_sdk - * Initialize the SDK} + * {@link https://firebase.google.com/docs/admin/setup#initialize_the_sdk | Initialize the SDK} * for more details. * * @example @@ -148,10 +132,10 @@ export function cert(serviceAccountPathOrObject: string | ServiceAccount, httpAg * @param refreshTokenPathOrObject The path to a Google * OAuth2 refresh token JSON file or an object representing a Google OAuth2 * refresh token. - * @param httpAgent Optional [HTTP Agent](https://nodejs.org/api/http.html#http_class_http_agent) + * @param httpAgent Optional {@link https://nodejs.org/api/http.html#http_class_http_agent | HTTP Agent} * to be used when retrieving access tokens from Google token servers. * - * @return A credential authenticated via the + * @returns A credential authenticated via the * provided service account that can be used to initialize an app. */ export function refreshToken(refreshTokenPathOrObject: string | object, httpAgent?: Agent): Credential { diff --git a/src/app/credential.ts b/src/app/credential.ts index 82e3e1ccc1..2453a97242 100644 --- a/src/app/credential.ts +++ b/src/app/credential.ts @@ -42,12 +42,7 @@ export interface Credential { * Returns a Google OAuth2 access token object used to authenticate with * Firebase services. * - * This object contains the following properties: - * * `access_token` (`string`): The actual Google OAuth2 access token. - * * `expires_in` (`number`): The number of seconds from when the token was - * issued that it expires. - * - * @return A Google OAuth2 access token object. + * @returns A Google OAuth2 access token object. */ getAccessToken(): Promise; } \ No newline at end of file diff --git a/src/app/firebase-app.ts b/src/app/firebase-app.ts index 2ccf7cd04a..62519fe9fe 100644 --- a/src/app/firebase-app.ts +++ b/src/app/firebase-app.ts @@ -192,7 +192,7 @@ export class FirebaseApp implements app.App { /** * Returns the Auth service instance associated with this app. * - * @return The Auth service instance of this app. + * @returns The Auth service instance of this app. */ public auth(): Auth { const fn = require('../auth/index').getAuth; @@ -202,7 +202,7 @@ export class FirebaseApp implements app.App { /** * Returns the Database service for the specified URL, and the current app. * - * @return The Database service instance of this app. + * @returns The Database service instance of this app. */ public database(url?: string): Database { const fn = require('../database/index').getDatabaseWithUrl; @@ -212,7 +212,7 @@ export class FirebaseApp implements app.App { /** * Returns the Messaging service instance associated with this app. * - * @return The Messaging service instance of this app. + * @returns The Messaging service instance of this app. */ public messaging(): Messaging { const fn = require('../messaging/index').getMessaging; @@ -222,7 +222,7 @@ export class FirebaseApp implements app.App { /** * Returns the Storage service instance associated with this app. * - * @return The Storage service instance of this app. + * @returns The Storage service instance of this app. */ public storage(): Storage { const fn = require('../storage/index').getStorage; @@ -237,7 +237,7 @@ export class FirebaseApp implements app.App { /** * Returns the InstanceId service instance associated with this app. * - * @return The InstanceId service instance of this app. + * @returns The InstanceId service instance of this app. */ public instanceId(): InstanceId { const fn = require('../instance-id/index').getInstanceId; @@ -247,7 +247,7 @@ export class FirebaseApp implements app.App { /** * Returns the MachineLearning service instance associated with this app. * - * @return The Machine Learning service instance of this app + * @returns The Machine Learning service instance of this app */ public machineLearning(): MachineLearning { const fn = require('../machine-learning/index').getMachineLearning; @@ -257,7 +257,7 @@ export class FirebaseApp implements app.App { /** * Returns the ProjectManagement service instance associated with this app. * - * @return The ProjectManagement service instance of this app. + * @returns The ProjectManagement service instance of this app. */ public projectManagement(): ProjectManagement { const fn = require('../project-management/index').getProjectManagement; @@ -267,7 +267,7 @@ export class FirebaseApp implements app.App { /** * Returns the SecurityRules service instance associated with this app. * - * @return The SecurityRules service instance of this app. + * @returns The SecurityRules service instance of this app. */ public securityRules(): SecurityRules { const fn = require('../security-rules/index').getSecurityRules; @@ -277,7 +277,7 @@ export class FirebaseApp implements app.App { /** * Returns the RemoteConfig service instance associated with this app. * - * @return The RemoteConfig service instance of this app. + * @returns The RemoteConfig service instance of this app. */ public remoteConfig(): RemoteConfig { const fn = require('../remote-config/index').getRemoteConfig; @@ -287,7 +287,7 @@ export class FirebaseApp implements app.App { /** * Returns the name of the FirebaseApp instance. * - * @return The name of the FirebaseApp instance. + * @returns The name of the FirebaseApp instance. */ get name(): string { this.checkDestroyed_(); @@ -297,7 +297,7 @@ export class FirebaseApp implements app.App { /** * Returns the options for the FirebaseApp instance. * - * @return The options for the FirebaseApp instance. + * @returns The options for the FirebaseApp instance. */ get options(): AppOptions { this.checkDestroyed_(); @@ -314,7 +314,7 @@ export class FirebaseApp implements app.App { /** * Deletes the FirebaseApp instance. * - * @return An empty Promise fulfilled once the FirebaseApp instance is deleted. + * @returns An empty Promise fulfilled once the FirebaseApp instance is deleted. */ public delete(): Promise { this.checkDestroyed_(); diff --git a/src/app/firebase-namespace.ts b/src/app/firebase-namespace.ts index f7c0280d53..c8af35247d 100644 --- a/src/app/firebase-namespace.ts +++ b/src/app/firebase-namespace.ts @@ -72,7 +72,7 @@ export class FirebaseNamespaceInternals { * to a file. * @param appName Optional name of the FirebaseApp instance. * - * @return A new App instance. + * @returns A new App instance. */ public initializeApp(options?: AppOptions, appName = DEFAULT_APP_NAME): App { if (typeof options === 'undefined') { @@ -114,7 +114,7 @@ export class FirebaseNamespaceInternals { * if no name is provided). * * @param appName Optional name of the FirebaseApp instance to return. - * @return The App instance which has the provided name. + * @returns The App instance which has the provided name. */ public app(appName = DEFAULT_APP_NAME): App { if (typeof appName !== 'string' || appName === '') { @@ -360,7 +360,7 @@ export class FirebaseNamespace { * otherwise it will be assumed to be pointing to a file. * @param appName Optional name of the FirebaseApp instance. * - * @return A new FirebaseApp instance. + * @returns A new FirebaseApp instance. */ public initializeApp(options?: AppOptions, appName?: string): App { return this.INTERNAL.initializeApp(options, appName); @@ -371,7 +371,7 @@ export class FirebaseNamespace { * if no name is provided). * * @param appName Optional name of the FirebaseApp instance to return. - * @return The FirebaseApp instance which has the provided name. + * @returns The FirebaseApp instance which has the provided name. */ public app(appName?: string): App { return this.INTERNAL.app(appName); diff --git a/src/auth/action-code-settings-builder.ts b/src/auth/action-code-settings-builder.ts index ec63e4ea63..4ebc4df19c 100644 --- a/src/auth/action-code-settings-builder.ts +++ b/src/auth/action-code-settings-builder.ts @@ -223,7 +223,7 @@ export class ActionCodeSettingsBuilder { * Returns the corresponding constructed server request corresponding to the * current ActionCodeSettings. * - * @return {EmailActionCodeRequest} The constructed EmailActionCodeRequest request. + * @returns The constructed EmailActionCodeRequest request. */ public buildRequest(): EmailActionCodeRequest { const request: { [key: string]: any } = { diff --git a/src/auth/auth-api-request.ts b/src/auth/auth-api-request.ts index 86abb109e3..69ac909b4e 100644 --- a/src/auth/auth-api-request.ts +++ b/src/auth/auth-api-request.ts @@ -126,8 +126,8 @@ class AuthResourceUrlBuilder { /** * The resource URL builder constructor. * - * @param {string} projectId The resource project ID. - * @param {string} version The endpoint API version. + * @param projectId The resource project ID. + * @param version The endpoint API version. * @constructor */ constructor(protected app: App, protected version: string = 'v1') { @@ -143,10 +143,10 @@ class AuthResourceUrlBuilder { /** * Returns the resource URL corresponding to the provided parameters. * - * @param {string=} api The backend API name. - * @param {object=} params The optional additional parameters to substitute in the + * @param api The backend API name. + * @param params The optional additional parameters to substitute in the * URL path. - * @return {Promise} The corresponding resource URL. + * @returns The corresponding resource URL. */ public getUrl(api?: string, params?: object): Promise { return this.getProjectId() @@ -190,9 +190,9 @@ class TenantAwareAuthResourceUrlBuilder extends AuthResourceUrlBuilder { /** * The tenant aware resource URL builder constructor. * - * @param {string} projectId The resource project ID. - * @param {string} version The endpoint API version. - * @param {string} tenantId The tenant ID. + * @param projectId The resource project ID. + * @param version The endpoint API version. + * @param tenantId The tenant ID. * @constructor */ constructor(protected app: App, protected version: string, protected tenantId: string) { @@ -209,10 +209,10 @@ class TenantAwareAuthResourceUrlBuilder extends AuthResourceUrlBuilder { /** * Returns the resource URL corresponding to the provided parameters. * - * @param {string=} api The backend API name. - * @param {object=} params The optional additional parameters to substitute in the + * @param api The backend API name. + * @param params The optional additional parameters to substitute in the * URL path. - * @return {Promise} The corresponding resource URL. + * @returns The corresponding resource URL. */ public getUrl(api?: string, params?: object): Promise { return super.getUrl(api, params) @@ -309,7 +309,7 @@ function validateAuthFactorInfo(request: AuthFactorInfo, writeOperationType: Wri * are removed from the original request. If an invalid field is passed * an error is thrown. * - * @param {any} request The providerUserInfo request object. + * @param request The providerUserInfo request object. */ function validateProviderUserInfo(request: any): void { const validKeys = { @@ -1013,8 +1013,8 @@ export abstract class AbstractAuthRequestHandler { private projectConfigUrlBuilder: AuthResourceUrlBuilder; /** - * @param {any} response The response to check for errors. - * @return {string|null} The error code if present; null otherwise. + * @param response The response to check for errors. + * @returns The error code if present; null otherwise. */ private static getErrorCode(response: any): string | null { return (validator.isNonNullObject(response) && response.error && response.error.message) || null; @@ -1062,7 +1062,7 @@ export abstract class AbstractAuthRequestHandler { } /** - * @param {FirebaseApp} app The app used to fetch access tokens to sign API requests. + * @param app The app used to fetch access tokens to sign API requests. * @constructor */ constructor(protected readonly app: App) { @@ -1081,10 +1081,10 @@ export abstract class AbstractAuthRequestHandler { * session management (set as a server side session cookie with custom cookie policy). * The session cookie JWT will have the same payload claims as the provided ID token. * - * @param {string} idToken The Firebase ID token to exchange for a session cookie. - * @param {number} expiresIn The session cookie duration in milliseconds. + * @param idToken The Firebase ID token to exchange for a session cookie. + * @param expiresIn The session cookie duration in milliseconds. * - * @return {Promise} A promise that resolves on success with the created session cookie. + * @returns A promise that resolves on success with the created session cookie. */ public createSessionCookie(idToken: string, expiresIn: number): Promise { const request = { @@ -1099,8 +1099,8 @@ export abstract class AbstractAuthRequestHandler { /** * Looks up a user by uid. * - * @param {string} uid The uid of the user to lookup. - * @return {Promise} A promise that resolves with the user information. + * @param uid The uid of the user to lookup. + * @returns A promise that resolves with the user information. */ public getAccountInfoByUid(uid: string): Promise { if (!validator.isUid(uid)) { @@ -1116,8 +1116,8 @@ export abstract class AbstractAuthRequestHandler { /** * Looks up a user by email. * - * @param {string} email The email of the user to lookup. - * @return {Promise} A promise that resolves with the user information. + * @param email The email of the user to lookup. + * @returns A promise that resolves with the user information. */ public getAccountInfoByEmail(email: string): Promise { if (!validator.isEmail(email)) { @@ -1133,8 +1133,8 @@ export abstract class AbstractAuthRequestHandler { /** * Looks up a user by phone number. * - * @param {string} phoneNumber The phone number of the user to lookup. - * @return {Promise} A promise that resolves with the user information. + * @param phoneNumber The phone number of the user to lookup. + * @returns A promise that resolves with the user information. */ public getAccountInfoByPhoneNumber(phoneNumber: string): Promise { if (!validator.isPhoneNumber(phoneNumber)) { @@ -1165,9 +1165,9 @@ export abstract class AbstractAuthRequestHandler { /** * Looks up multiple users by their identifiers (uid, email, etc). * - * @param {UserIdentifier[]} identifiers The identifiers indicating the users + * @param identifiers The identifiers indicating the users * to be looked up. Must have <= 100 entries. - * @param {Promise} A promise that resolves with the set of successfully + * @param A promise that resolves with the set of successfully * looked up users. Possibly empty if no users were looked up. */ public getAccountInfoByIdentifiers(identifiers: UserIdentifier[]): Promise { @@ -1204,12 +1204,12 @@ export abstract class AbstractAuthRequestHandler { * Exports the users (single batch only) with a size of maxResults and starting from * the offset as specified by pageToken. * - * @param {number=} maxResults The page size, 1000 if undefined. This is also the maximum + * @param maxResults The page size, 1000 if undefined. This is also the maximum * allowed limit. - * @param {string=} pageToken The next page token. If not specified, returns users starting + * @param pageToken The next page token. If not specified, returns users starting * without any offset. Users are returned in the order they were created from oldest to * newest, relative to the page token offset. - * @return {Promise} A promise that resolves with the current batch of downloaded + * @returns A promise that resolves with the current batch of downloaded * users and the next page token if available. For the last page, an empty list of users * and no page token are returned. */ @@ -1241,10 +1241,10 @@ export abstract class AbstractAuthRequestHandler { * At most, 1000 users are allowed to be imported one at a time. * When importing a list of password users, UserImportOptions are required to be specified. * - * @param {UserImportRecord[]} users The list of user records to import to Firebase Auth. - * @param {UserImportOptions=} options The user import options, required when the users provided + * @param users The list of user records to import to Firebase Auth. + * @param options The user import options, required when the users provided * include password credentials. - * @return {Promise} A promise that resolves when the operation completes + * @returns A promise that resolves when the operation completes * with the result of the import. This includes the number of successful imports, the number * of failed uploads and their corresponding errors. */ @@ -1283,8 +1283,8 @@ export abstract class AbstractAuthRequestHandler { /** * Deletes an account identified by a uid. * - * @param {string} uid The uid of the user to delete. - * @return {Promise} A promise that resolves when the user is deleted. + * @param uid The uid of the user to delete. + * @returns A promise that resolves when the user is deleted. */ public deleteAccount(uid: string): Promise { if (!validator.isUid(uid)) { @@ -1324,9 +1324,9 @@ export abstract class AbstractAuthRequestHandler { /** * Sets additional developer claims on an existing user identified by provided UID. * - * @param {string} uid The user to edit. - * @param {object} customUserClaims The developer claims to set. - * @return {Promise} A promise that resolves when the operation completes + * @param uid The user to edit. + * @param customUserClaims The developer claims to set. + * @returns A promise that resolves when the operation completes * with the user id that was edited. */ public setCustomUserClaims(uid: string, customUserClaims: object | null): Promise { @@ -1359,9 +1359,9 @@ export abstract class AbstractAuthRequestHandler { /** * Edits an existing user. * - * @param {string} uid The user to edit. - * @param {object} properties The properties to set on the user. - * @return {Promise} A promise that resolves when the operation completes + * @param uid The user to edit. + * @param properties The properties to set on the user. + * @returns A promise that resolves when the operation completes * with the user id that was edited. */ public updateExistingAccount(uid: string, properties: UpdateRequest): Promise { @@ -1503,8 +1503,8 @@ export abstract class AbstractAuthRequestHandler { * the same second as the revocation will still be valid. If there is a chance that a token * was minted in the last second, delay for 1 second before revoking. * - * @param {string} uid The user whose tokens are to be revoked. - * @return {Promise} A promise that resolves when the operation completes + * @param uid The user whose tokens are to be revoked. + * @returns A promise that resolves when the operation completes * successfully with the user id of the corresponding user. */ public revokeRefreshTokens(uid: string): Promise { @@ -1526,8 +1526,8 @@ export abstract class AbstractAuthRequestHandler { /** * Create a new user with the properties supplied. * - * @param {object} properties The properties to set on the user. - * @return {Promise} A promise that resolves when the operation completes + * @param properties The properties to set on the user. + * @returns A promise that resolves when the operation completes * with the user id that was created. */ public createNewAccount(properties: CreateRequest): Promise { @@ -1589,13 +1589,13 @@ export abstract class AbstractAuthRequestHandler { * Generates the out of band email action link for the email specified using the action code settings provided. * Returns a promise that resolves with the generated link. * - * @param {string} requestType The request type. This could be either used for password reset, + * @param requestType The request type. This could be either used for password reset, * email verification, email link sign-in. - * @param {string} email The email of the user the link is being sent to. - * @param {ActionCodeSettings=} actionCodeSettings The optional action code setings which defines whether + * @param email The email of the user the link is being sent to. + * @param actionCodeSettings The optional action code setings which defines whether * the link is to be handled by a mobile app and the additional state information to be passed in the * deep link, etc. Required when requestType == 'EMAIL_SIGNIN' - * @return {Promise} A promise that resolves with the email action link. + * @returns A promise that resolves with the email action link. */ public getEmailActionLink( requestType: string, email: string, @@ -1629,8 +1629,8 @@ export abstract class AbstractAuthRequestHandler { /** * Looks up an OIDC provider configuration by provider ID. * - * @param {string} providerId The provider identifier of the configuration to lookup. - * @return {Promise} A promise that resolves with the provider configuration information. + * @param providerId The provider identifier of the configuration to lookup. + * @returns A promise that resolves with the provider configuration information. */ public getOAuthIdpConfig(providerId: string): Promise { if (!OIDCConfig.isProviderId(providerId)) { @@ -1643,12 +1643,12 @@ export abstract class AbstractAuthRequestHandler { * Lists the OIDC configurations (single batch only) with a size of maxResults and starting from * the offset as specified by pageToken. * - * @param {number=} maxResults The page size, 100 if undefined. This is also the maximum + * @param maxResults The page size, 100 if undefined. This is also the maximum * allowed limit. - * @param {string=} pageToken The next page token. If not specified, returns OIDC configurations + * @param pageToken The next page token. If not specified, returns OIDC configurations * without any offset. Configurations are returned in the order they were created from oldest to * newest, relative to the page token offset. - * @return {Promise} A promise that resolves with the current batch of downloaded + * @returns A promise that resolves with the current batch of downloaded * OIDC configurations and the next page token if available. For the last page, an empty list of provider * configuration and no page token are returned. */ @@ -1675,8 +1675,8 @@ export abstract class AbstractAuthRequestHandler { /** * Deletes an OIDC configuration identified by a providerId. * - * @param {string} providerId The identifier of the OIDC configuration to delete. - * @return {Promise} A promise that resolves when the OIDC provider is deleted. + * @param providerId The identifier of the OIDC configuration to delete. + * @returns A promise that resolves when the OIDC provider is deleted. */ public deleteOAuthIdpConfig(providerId: string): Promise { if (!OIDCConfig.isProviderId(providerId)) { @@ -1691,8 +1691,8 @@ export abstract class AbstractAuthRequestHandler { /** * Creates a new OIDC provider configuration with the properties provided. * - * @param {AuthProviderConfig} options The properties to set on the new OIDC provider configuration to be created. - * @return {Promise} A promise that resolves with the newly created OIDC + * @param options The properties to set on the new OIDC provider configuration to be created. + * @returns A promise that resolves with the newly created OIDC * configuration. */ public createOAuthIdpConfig(options: OIDCAuthProviderConfig): Promise { @@ -1719,9 +1719,9 @@ export abstract class AbstractAuthRequestHandler { /** * Updates an existing OIDC provider configuration with the properties provided. * - * @param {string} providerId The provider identifier of the OIDC configuration to update. - * @param {OIDCUpdateAuthProviderRequest} options The properties to update on the existing configuration. - * @return {Promise} A promise that resolves with the modified provider + * @param providerId The provider identifier of the OIDC configuration to update. + * @param options The properties to update on the existing configuration. + * @returns A promise that resolves with the modified provider * configuration. */ public updateOAuthIdpConfig( @@ -1752,8 +1752,8 @@ export abstract class AbstractAuthRequestHandler { /** * Looks up an SAML provider configuration by provider ID. * - * @param {string} providerId The provider identifier of the configuration to lookup. - * @return {Promise} A promise that resolves with the provider configuration information. + * @param providerId The provider identifier of the configuration to lookup. + * @returns A promise that resolves with the provider configuration information. */ public getInboundSamlConfig(providerId: string): Promise { if (!SAMLConfig.isProviderId(providerId)) { @@ -1766,12 +1766,12 @@ export abstract class AbstractAuthRequestHandler { * Lists the SAML configurations (single batch only) with a size of maxResults and starting from * the offset as specified by pageToken. * - * @param {number=} maxResults The page size, 100 if undefined. This is also the maximum + * @param maxResults The page size, 100 if undefined. This is also the maximum * allowed limit. - * @param {string=} pageToken The next page token. If not specified, returns SAML configurations starting + * @param pageToken The next page token. If not specified, returns SAML configurations starting * without any offset. Configurations are returned in the order they were created from oldest to * newest, relative to the page token offset. - * @return {Promise} A promise that resolves with the current batch of downloaded + * @returns A promise that resolves with the current batch of downloaded * SAML configurations and the next page token if available. For the last page, an empty list of provider * configuration and no page token are returned. */ @@ -1798,8 +1798,8 @@ export abstract class AbstractAuthRequestHandler { /** * Deletes a SAML configuration identified by a providerId. * - * @param {string} providerId The identifier of the SAML configuration to delete. - * @return {Promise} A promise that resolves when the SAML provider is deleted. + * @param providerId The identifier of the SAML configuration to delete. + * @returns A promise that resolves when the SAML provider is deleted. */ public deleteInboundSamlConfig(providerId: string): Promise { if (!SAMLConfig.isProviderId(providerId)) { @@ -1814,8 +1814,8 @@ export abstract class AbstractAuthRequestHandler { /** * Creates a new SAML provider configuration with the properties provided. * - * @param {AuthProviderConfig} options The properties to set on the new SAML provider configuration to be created. - * @return {Promise} A promise that resolves with the newly created SAML + * @param options The properties to set on the new SAML provider configuration to be created. + * @returns A promise that resolves with the newly created SAML * configuration. */ public createInboundSamlConfig(options: SAMLAuthProviderConfig): Promise { @@ -1842,9 +1842,9 @@ export abstract class AbstractAuthRequestHandler { /** * Updates an existing SAML provider configuration with the properties provided. * - * @param {string} providerId The provider identifier of the SAML configuration to update. - * @param {SAMLUpdateAuthProviderRequest} options The properties to update on the existing configuration. - * @return {Promise} A promise that resolves with the modified provider + * @param providerId The provider identifier of the SAML configuration to update. + * @param options The properties to update on the existing configuration. + * @returns A promise that resolves with the modified provider * configuration. */ public updateInboundSamlConfig( @@ -1875,11 +1875,11 @@ export abstract class AbstractAuthRequestHandler { /** * Invokes the request handler based on the API settings object passed. * - * @param {AuthResourceUrlBuilder} urlBuilder The URL builder for Auth endpoints. - * @param {ApiSettings} apiSettings The API endpoint settings to apply to request and response. - * @param {object} requestData The request data. - * @param {object=} additionalResourceParams Additional resource related params if needed. - * @return {Promise} A promise that resolves with the response. + * @param urlBuilder The URL builder for Auth endpoints. + * @param apiSettings The API endpoint settings to apply to request and response. + * @param requestData The request data. + * @param additionalResourceParams Additional resource related params if needed. + * @returns A promise that resolves with the response. */ protected invokeRequestHandler( urlBuilder: AuthResourceUrlBuilder, apiSettings: ApiSettings, @@ -1925,17 +1925,17 @@ export abstract class AbstractAuthRequestHandler { } /** - * @return {AuthResourceUrlBuilder} A new Auth user management resource URL builder instance. + * @returns A new Auth user management resource URL builder instance. */ protected abstract newAuthUrlBuilder(): AuthResourceUrlBuilder; /** - * @return {AuthResourceUrlBuilder} A new project config resource URL builder instance. + * @returns A new project config resource URL builder instance. */ protected abstract newProjectConfigUrlBuilder(): AuthResourceUrlBuilder; /** - * @return {AuthResourceUrlBuilder} The current Auth user management resource URL builder. + * @returns The current Auth user management resource URL builder. */ private getAuthUrlBuilder(): AuthResourceUrlBuilder { if (!this.authUrlBuilder) { @@ -1945,7 +1945,7 @@ export abstract class AbstractAuthRequestHandler { } /** - * @return {AuthResourceUrlBuilder} The current project config resource URL builder. + * @returns The current project config resource URL builder. */ private getProjectConfigUrlBuilder(): AuthResourceUrlBuilder { if (!this.projectConfigUrlBuilder) { @@ -2034,7 +2034,7 @@ export class AuthRequestHandler extends AbstractAuthRequestHandler { /** * The FirebaseAuthRequestHandler constructor used to initialize an instance using a FirebaseApp. * - * @param {FirebaseApp} app The app used to fetch access tokens to sign API requests. + * @param app The app used to fetch access tokens to sign API requests. * @constructor. */ constructor(app: App) { @@ -2043,14 +2043,14 @@ export class AuthRequestHandler extends AbstractAuthRequestHandler { } /** - * @return {AuthResourceUrlBuilder} A new Auth user management resource URL builder instance. + * @returns A new Auth user management resource URL builder instance. */ protected newAuthUrlBuilder(): AuthResourceUrlBuilder { return new AuthResourceUrlBuilder(this.app, 'v1'); } /** - * @return {AuthResourceUrlBuilder} A new project config resource URL builder instance. + * @returns A new project config resource URL builder instance. */ protected newProjectConfigUrlBuilder(): AuthResourceUrlBuilder { return new AuthResourceUrlBuilder(this.app, 'v2'); @@ -2059,8 +2059,8 @@ export class AuthRequestHandler extends AbstractAuthRequestHandler { /** * Looks up a tenant by tenant ID. * - * @param {string} tenantId The tenant identifier of the tenant to lookup. - * @return {Promise} A promise that resolves with the tenant information. + * @param tenantId The tenant identifier of the tenant to lookup. + * @returns A promise that resolves with the tenant information. */ public getTenant(tenantId: string): Promise { if (!validator.isNonEmptyString(tenantId)) { @@ -2076,12 +2076,12 @@ export class AuthRequestHandler extends AbstractAuthRequestHandler { * Exports the tenants (single batch only) with a size of maxResults and starting from * the offset as specified by pageToken. * - * @param {number=} maxResults The page size, 1000 if undefined. This is also the maximum + * @param maxResults The page size, 1000 if undefined. This is also the maximum * allowed limit. - * @param {string=} pageToken The next page token. If not specified, returns tenants starting + * @param pageToken The next page token. If not specified, returns tenants starting * without any offset. Tenants are returned in the order they were created from oldest to * newest, relative to the page token offset. - * @return {Promise} A promise that resolves with the current batch of downloaded + * @returns A promise that resolves with the current batch of downloaded * tenants and the next page token if available. For the last page, an empty list of tenants * and no page token are returned. */ @@ -2109,8 +2109,8 @@ export class AuthRequestHandler extends AbstractAuthRequestHandler { /** * Deletes a tenant identified by a tenantId. * - * @param {string} tenantId The identifier of the tenant to delete. - * @return {Promise} A promise that resolves when the tenant is deleted. + * @param tenantId The identifier of the tenant to delete. + * @returns A promise that resolves when the tenant is deleted. */ public deleteTenant(tenantId: string): Promise { if (!validator.isNonEmptyString(tenantId)) { @@ -2125,8 +2125,8 @@ export class AuthRequestHandler extends AbstractAuthRequestHandler { /** * Creates a new tenant with the properties provided. * - * @param {TenantOptions} tenantOptions The properties to set on the new tenant to be created. - * @return {Promise} A promise that resolves with the newly created tenant object. + * @param tenantOptions The properties to set on the new tenant to be created. + * @returns A promise that resolves with the newly created tenant object. */ public createTenant(tenantOptions: CreateTenantRequest): Promise { try { @@ -2144,9 +2144,9 @@ export class AuthRequestHandler extends AbstractAuthRequestHandler { /** * Updates an existing tenant with the properties provided. * - * @param {string} tenantId The tenant identifier of the tenant to update. - * @param {TenantOptions} tenantOptions The properties to update on the existing tenant. - * @return {Promise} A promise that resolves with the modified tenant object. + * @param tenantId The tenant identifier of the tenant to update. + * @param tenantOptions The properties to update on the existing tenant. + * @returns A promise that resolves with the modified tenant object. */ public updateTenant(tenantId: string, tenantOptions: UpdateTenantRequest): Promise { if (!validator.isNonEmptyString(tenantId)) { @@ -2179,8 +2179,8 @@ export class TenantAwareAuthRequestHandler extends AbstractAuthRequestHandler { * The FirebaseTenantRequestHandler constructor used to initialize an instance using a * FirebaseApp and a tenant ID. * - * @param {FirebaseApp} app The app used to fetch access tokens to sign API requests. - * @param {string} tenantId The request handler's tenant ID. + * @param app The app used to fetch access tokens to sign API requests. + * @param tenantId The request handler's tenant ID. * @constructor */ constructor(app: App, private readonly tenantId: string) { @@ -2188,14 +2188,14 @@ export class TenantAwareAuthRequestHandler extends AbstractAuthRequestHandler { } /** - * @return {AuthResourceUrlBuilder} A new Auth user management resource URL builder instance. + * @returns A new Auth user management resource URL builder instance. */ protected newAuthUrlBuilder(): AuthResourceUrlBuilder { return new TenantAwareAuthResourceUrlBuilder(this.app, 'v1', this.tenantId); } /** - * @return {AuthResourceUrlBuilder} A new project config resource URL builder instance. + * @returns A new project config resource URL builder instance. */ protected newProjectConfigUrlBuilder(): AuthResourceUrlBuilder { return new TenantAwareAuthResourceUrlBuilder(this.app, 'v2', this.tenantId); @@ -2210,10 +2210,10 @@ export class TenantAwareAuthRequestHandler extends AbstractAuthRequestHandler { * Overrides the superclass methods by adding an additional check to match tenant IDs of * imported user records if present. * - * @param {UserImportRecord[]} users The list of user records to import to Firebase Auth. - * @param {UserImportOptions=} options The user import options, required when the users provided + * @param users The list of user records to import to Firebase Auth. + * @param options The user import options, required when the users provided * include password credentials. - * @return {Promise} A promise that resolves when the operation completes + * @returns A promise that resolves when the operation completes * with the result of the import. This includes the number of successful imports, the number * of failed uploads and their corresponding errors. */ diff --git a/src/auth/auth-config.ts b/src/auth/auth-config.ts index 793eb3addc..0c1fc2db36 100644 --- a/src/auth/auth-config.ts +++ b/src/auth/auth-config.ts @@ -495,7 +495,7 @@ export class MultiFactorAuthConfig implements MultiFactorConfig { * Throws an error if validation fails. * * @param options The options object to convert to a server request. - * @return The resulting server request. + * @returns The resulting server request. * @internal */ public static buildServerRequest(options: MultiFactorConfig): MultiFactorAuthServerConfig { @@ -599,7 +599,7 @@ export class MultiFactorAuthConfig implements MultiFactorConfig { }) } - /** @return The plain object representation of the multi-factor config instance. */ + /** @returns The plain object representation of the multi-factor config instance. */ public toJSON(): object { return { state: this.state, @@ -676,8 +676,8 @@ export class EmailSignInConfig implements EmailSignInProviderConfig { * Static method to convert a client side request to a EmailSignInConfigServerRequest. * Throws an error if validation fails. * - * @param {any} options The options object to convert to a server request. - * @return {EmailSignInConfigServerRequest} The resulting server request. + * @param options The options object to convert to a server request. + * @returns The resulting server request. * @internal */ public static buildServerRequest(options: EmailSignInProviderConfig): EmailSignInConfigServerRequest { @@ -695,7 +695,7 @@ export class EmailSignInConfig implements EmailSignInProviderConfig { /** * Validates the EmailSignInConfig options object. Throws an error on failure. * - * @param {any} options The options object to validate. + * @param options The options object to validate. */ private static validate(options: EmailSignInProviderConfig): void { // TODO: Validate the request. @@ -738,7 +738,7 @@ export class EmailSignInConfig implements EmailSignInProviderConfig { /** * The EmailSignInConfig constructor. * - * @param {any} response The server side response used to initialize the + * @param response The server side response used to initialize the * EmailSignInConfig object. * @constructor */ @@ -752,7 +752,7 @@ export class EmailSignInConfig implements EmailSignInProviderConfig { this.passwordRequired = !response.enableEmailLinkSignin; } - /** @return {object} The plain object representation of the email sign-in config. */ + /** @returns The plain object representation of the email sign-in config. */ public toJSON(): object { return { enabled: this.enabled, @@ -890,9 +890,9 @@ export class SAMLConfig implements SAMLAuthProviderConfig { * Throws an error if validation fails. If the request is not a SAMLConfig request, * returns null. * - * @param {SAMLAuthProviderRequest} options The options object to convert to a server request. - * @param {boolean=} ignoreMissingFields Whether to ignore missing fields. - * @return {?SAMLConfigServerRequest} The resulting server request or null if not valid. + * @param options The options object to convert to a server request. + * @param ignoreMissingFields Whether to ignore missing fields. + * @returns The resulting server request or null if not valid. */ public static buildServerRequest( options: Partial, @@ -934,8 +934,8 @@ export class SAMLConfig implements SAMLAuthProviderConfig { /** * Returns the provider ID corresponding to the resource name if available. * - * @param {string} resourceName The server side resource name. - * @return {?string} The provider ID corresponding to the resource, null otherwise. + * @param resourceName The server side resource name. + * @returns The provider ID corresponding to the resource, null otherwise. */ public static getProviderIdFromResourceName(resourceName: string): string | null { // name is of form projects/project1/inboundSamlConfigs/providerId1 @@ -947,8 +947,8 @@ export class SAMLConfig implements SAMLAuthProviderConfig { } /** - * @param {any} providerId The provider ID to check. - * @return {boolean} Whether the provider ID corresponds to a SAML provider. + * @param providerId The provider ID to check. + * @returns Whether the provider ID corresponds to a SAML provider. */ public static isProviderId(providerId: any): providerId is string { return validator.isNonEmptyString(providerId) && providerId.indexOf('saml.') === 0; @@ -957,8 +957,8 @@ export class SAMLConfig implements SAMLAuthProviderConfig { /** * Validates the SAMLConfig options object. Throws an error on failure. * - * @param {SAMLAuthProviderRequest} options The options object to validate. - * @param {boolean=} ignoreMissingFields Whether to ignore missing fields. + * @param options The options object to validate. + * @param ignoreMissingFields Whether to ignore missing fields. */ public static validate(options: Partial, ignoreMissingFields = false): void { const validKeys = { @@ -1117,7 +1117,7 @@ export class SAMLConfig implements SAMLAuthProviderConfig { this.displayName = response.displayName; } - /** @return The plain object representation of the SAMLConfig. */ + /** @returns The plain object representation of the SAMLConfig. */ public toJSON(): object { return { enabled: this.enabled, @@ -1154,7 +1154,7 @@ export class OIDCConfig implements OIDCAuthProviderConfig { * * @param options The options object to convert to a server request. * @param ignoreMissingFields Whether to ignore missing fields. - * @return The resulting server request or null if not valid. + * @returns The resulting server request or null if not valid. */ public static buildServerRequest( options: Partial, @@ -1177,8 +1177,8 @@ export class OIDCConfig implements OIDCAuthProviderConfig { /** * Returns the provider ID corresponding to the resource name if available. * - * @param {string} resourceName The server side resource name - * @return {?string} The provider ID corresponding to the resource, null otherwise. + * @param resourceName The server side resource name + * @returns The provider ID corresponding to the resource, null otherwise. */ public static getProviderIdFromResourceName(resourceName: string): string | null { // name is of form projects/project1/oauthIdpConfigs/providerId1 @@ -1190,8 +1190,8 @@ export class OIDCConfig implements OIDCAuthProviderConfig { } /** - * @param {any} providerId The provider ID to check. - * @return {boolean} Whether the provider ID corresponds to an OIDC provider. + * @param providerId The provider ID to check. + * @returns Whether the provider ID corresponds to an OIDC provider. */ public static isProviderId(providerId: any): providerId is string { return validator.isNonEmptyString(providerId) && providerId.indexOf('oidc.') === 0; @@ -1303,7 +1303,7 @@ export class OIDCConfig implements OIDCAuthProviderConfig { this.displayName = response.displayName; } - /** @return {OIDCAuthProviderConfig} The plain object representation of the OIDCConfig. */ + /** @returns The plain object representation of the OIDCConfig. */ public toJSON(): OIDCAuthProviderConfig { return { enabled: this.enabled, diff --git a/src/auth/auth.ts b/src/auth/auth.ts index 132631970f..4ad29f6d20 100644 --- a/src/auth/auth.ts +++ b/src/auth/auth.ts @@ -43,14 +43,16 @@ export class Auth extends BaseAuth { /** * Returns the app associated with this Auth instance. * - * @return The app associated with this Auth instance. + * @returns The app associated with this Auth instance. */ get app(): App { return this.app_; } /** - * @return The tenant manager instance associated with the current project. + * Returns the tenant manager instance associated with the current project. + * + * @returns The tenant manager instance associated with the current project. */ public tenantManager(): TenantManager { return this.tenantManager_; diff --git a/src/auth/base-auth.ts b/src/auth/base-auth.ts index a68299237a..9f155b607c 100644 --- a/src/auth/base-auth.ts +++ b/src/auth/base-auth.ts @@ -37,7 +37,7 @@ import { import { UserImportOptions, UserImportRecord, UserImportResult } from './user-import-builder'; import { ActionCodeSettings } from './action-code-settings-builder'; -/** Represents the result of the {@link auth.Auth.getUsers} API. */ +/** Represents the result of the {@link BaseAuth.getUsers} API. */ export interface GetUsersResult { /** * Set of user records, corresponding to the set of users that were @@ -70,8 +70,7 @@ export interface ListUsersResult { } /** - * Represents the result of the - * {@link auth.Auth.deleteUsers `deleteUsers()`} + * Represents the result of the {@link BaseAuth.deleteUsers}. * API. */ export interface DeleteUsersResult { @@ -90,14 +89,14 @@ export interface DeleteUsersResult { /** * A list of `FirebaseArrayIndexError` instances describing the errors that * were encountered during the deletion. Length of this list is equal to - * the return value of [`failureCount`](#failureCount). + * the return value of {@link DeleteUsersResult.failureCount}. */ errors: FirebaseArrayIndexError[]; } /** * Interface representing the session cookie options needed for the - * {@link auth.Auth.createSessionCookie `createSessionCookie()`} method. + * {@link BaseAuth.createSessionCookie} method. */ export interface SessionCookieOptions { @@ -152,14 +151,14 @@ export abstract class BaseAuth { * methods. (Tenant-aware instances will also embed the tenant ID in the * token.) * - * See [Create Custom Tokens](/docs/auth/admin/create-custom-tokens) for code - * samples and detailed documentation. + * See {@link https://firebase.google.com/docs/auth/admin/create-custom-tokens | Create Custom Tokens} + * for code samples and detailed documentation. * * @param uid The `uid` to use as the custom token's subject. * @param developerClaims Optional additional claims to include * in the custom token's payload. * - * @return A promise fulfilled with a custom token for the + * @returns A promise fulfilled with a custom token for the * provided `uid` and payload. */ public createCustomToken(uid: string, developerClaims?: object): Promise { @@ -173,8 +172,8 @@ export abstract class BaseAuth { * An optional flag can be passed to additionally check whether the ID token * was revoked. * - * See [Verify ID Tokens](/docs/auth/admin/verify-id-tokens) for code samples - * and detailed documentation. + * See {@link https://firebase.google.com/docs/auth/admin/verify-id-tokens | Verify ID Tokens} + * for code samples and detailed documentation. * * @param idToken The ID token to verify. * @param checkRevoked Whether to check if the ID token was revoked. @@ -182,7 +181,7 @@ export abstract class BaseAuth { * the `tokensValidAfterTime` time for the corresponding user. * When not specified, this additional check is not applied. * - * @return A promise fulfilled with the + * @returns A promise fulfilled with the * token's decoded claims if the ID token is valid; otherwise, a rejected * promise. */ @@ -203,12 +202,12 @@ export abstract class BaseAuth { /** * Gets the user data for the user corresponding to a given `uid`. * - * See [Retrieve user data](/docs/auth/admin/manage-users#retrieve_user_data) + * See {@link https://firebase.google.com/docs/auth/admin/manage-users#retrieve_user_data | Retrieve user data} * for code samples and detailed documentation. * * @param uid The `uid` corresponding to the user whose data to fetch. * - * @return A promise fulfilled with the user + * @returns A promise fulfilled with the user * data corresponding to the provided `uid`. */ public getUser(uid: string): Promise { @@ -222,13 +221,13 @@ export abstract class BaseAuth { /** * Gets the user data for the user corresponding to a given email. * - * See [Retrieve user data](/docs/auth/admin/manage-users#retrieve_user_data) + * See {@link https://firebase.google.com/docs/auth/admin/manage-users#retrieve_user_data | Retrieve user data} * for code samples and detailed documentation. * * @param email The email corresponding to the user whose data to * fetch. * - * @return A promise fulfilled with the user + * @returns A promise fulfilled with the user * data corresponding to the provided email. */ public getUserByEmail(email: string): Promise { @@ -243,13 +242,13 @@ export abstract class BaseAuth { * Gets the user data for the user corresponding to a given phone number. The * phone number has to conform to the E.164 specification. * - * See [Retrieve user data](/docs/auth/admin/manage-users#retrieve_user_data) + * See {@link https://firebase.google.com/docs/auth/admin/manage-users#retrieve_user_data | Retrieve user data} * for code samples and detailed documentation. * * @param phoneNumber The phone number corresponding to the user whose * data to fetch. * - * @return A promise fulfilled with the user + * @returns A promise fulfilled with the user * data corresponding to the provided phone number. */ public getUserByPhoneNumber(phoneNumber: string): Promise { @@ -263,14 +262,14 @@ export abstract class BaseAuth { /** * Gets the user data for the user corresponding to a given provider id. * - * See [Retrieve user data](/docs/auth/admin/manage-users#retrieve_user_data) + * See {@link https://firebase.google.com/docs/auth/admin/manage-users#retrieve_user_data | Retrieve user data} * for code samples and detailed documentation. * * @param providerId The provider ID, for example, "google.com" for the * Google provider. * @param uid The user identifier for the given provider. * - * @return A promise fulfilled with the user data corresponding to the + * @returns A promise fulfilled with the user data corresponding to the * given provider id. */ public getUserByProviderUid(providerId: string, uid: string): Promise { @@ -301,7 +300,7 @@ export abstract class BaseAuth { * * @param identifiers The identifiers used to indicate which user records should be returned. * Must have <= 100 entries. - * @return {Promise} A promise that resolves to the corresponding user records. + * @returns A promise that resolves to the corresponding user records. * @throws FirebaseAuthError If any of the identifiers are invalid or if more than 100 * identifiers are specified. */ @@ -350,14 +349,14 @@ export abstract class BaseAuth { * starting from the offset as specified by `pageToken`. This is used to * retrieve all the users of a specified project in batches. * - * See [List all users](/docs/auth/admin/manage-users#list_all_users) + * See {@link https://firebase.google.com/docs/auth/admin/manage-users#list_all_users | List all users} * for code samples and detailed documentation. * * @param maxResults The page size, 1000 if undefined. This is also * the maximum allowed limit. * @param pageToken The next page token. If not specified, returns * users starting without any offset. - * @return A promise that resolves with + * @returns A promise that resolves with * the current batch of downloaded users and the next page token. */ public listUsers(maxResults?: number, pageToken?: string): Promise { @@ -385,13 +384,13 @@ export abstract class BaseAuth { /** * Creates a new user. * - * See [Create a user](/docs/auth/admin/manage-users#create_a_user) for code - * samples and detailed documentation. + * See {@link https://firebase.google.com/docs/auth/admin/manage-users#create_a_user | Create a user} + * for code samples and detailed documentation. * * @param properties The properties to set on the * new user record to be created. * - * @return A promise fulfilled with the user + * @returns A promise fulfilled with the user * data corresponding to the newly created user. */ public createUser(properties: CreateRequest): Promise { @@ -414,12 +413,12 @@ export abstract class BaseAuth { /** * Deletes an existing user. * - * See [Delete a user](/docs/auth/admin/manage-users#delete_a_user) for code - * samples and detailed documentation. + * See {@link https://firebase.google.com/docs/auth/admin/manage-users#delete_a_user | Delete a user} + * for code samples and detailed documentation. * * @param uid The `uid` corresponding to the user to delete. * - * @return An empty promise fulfilled once the user has been + * @returns An empty promise fulfilled once the user has been * deleted. */ public deleteUser(uid: string): Promise { @@ -447,7 +446,7 @@ export abstract class BaseAuth { * * @param uids The `uids` corresponding to the users to delete. * - * @return A Promise that resolves to the total number of successful/failed + * @returns A Promise that resolves to the total number of successful/failed * deletions, as well as the array of errors that corresponds to the * failed deletions. */ @@ -498,14 +497,14 @@ export abstract class BaseAuth { /** * Updates an existing user. * - * See [Update a user](/docs/auth/admin/manage-users#update_a_user) for code - * samples and detailed documentation. + * See {@link https://firebsae.google.com/docs/auth/admin/manage-users#update_a_user | Update a user} + * for code samples and detailed documentation. * * @param uid The `uid` corresponding to the user to update. * @param properties The properties to update on * the provided user. * - * @return A promise fulfilled with the + * @returns A promise fulfilled with the * updated user data. */ public updateUser(uid: string, properties: UpdateRequest): Promise { @@ -569,8 +568,8 @@ export abstract class BaseAuth { * is used (sub, iat, iss, etc), an error is thrown. They are set on the * authenticated user's ID token JWT. * - * See - * [Defining user roles and access levels](/docs/auth/admin/custom-claims) + * See {@link https://firebase.google.com/docs/auth/admin/custom-claims | + * Defining user roles and access levels} * for code samples and detailed documentation. * * @param uid The `uid` of the user to edit. @@ -580,7 +579,7 @@ export abstract class BaseAuth { * user's ID token which is transmitted on every authenticated request. * For profile non-access related user attributes, use database or other * separate storage systems. - * @return A promise that resolves when the operation completes + * @returns A promise that resolves when the operation completes * successfully. */ public setCustomUserClaims(uid: string, customUserClaims: object | null): Promise { @@ -593,22 +592,20 @@ export abstract class BaseAuth { /** * Revokes all refresh tokens for an existing user. * - * This API will update the user's - * {@link auth.UserRecord.tokensValidAfterTime `tokensValidAfterTime`} to + * This API will update the user's {@link UserRecord.tokensValidAfterTime} to * the current UTC. It is important that the server on which this is called has * its clock set correctly and synchronized. * * While this will revoke all sessions for a specified user and disable any * new ID tokens for existing sessions from getting minted, existing ID tokens * may remain active until their natural expiration (one hour). To verify that - * ID tokens are revoked, use - * {@link auth.Auth.verifyIdToken `verifyIdToken(idToken, true)`} + * ID tokens are revoked, use {@link BaseAuth.verifyIdToken} * where `checkRevoked` is set to true. * * @param uid The `uid` corresponding to the user whose refresh tokens * are to be revoked. * - * @return An empty promise fulfilled once the user's refresh + * @returns An empty promise fulfilled once the user's refresh * tokens have been revoked. */ public revokeRefreshTokens(uid: string): Promise { @@ -622,7 +619,7 @@ export abstract class BaseAuth { * Imports the provided list of users into Firebase Auth. * A maximum of 1000 users are allowed to be imported one at a time. * When importing users with passwords, - * {@link auth.UserImportOptions `UserImportOptions`} are required to be + * {@link UserImportOptions} are required to be * specified. * This operation is optimized for bulk imports and will ignore checks on `uid`, * `email` and other identifier uniqueness which could result in duplications. @@ -630,7 +627,7 @@ export abstract class BaseAuth { * @param users The list of user records to import to Firebase Auth. * @param options The user import options, required when the users provided include * password credentials. - * @return A promise that resolves when + * @returns A promise that resolves when * the operation completes with the result of the import. This includes the * number of successful imports, the number of failed imports and their * corresponding errors. @@ -646,15 +643,15 @@ export abstract class BaseAuth { * policy, and be used for session management. The session cookie JWT will have * the same payload claims as the provided ID token. * - * See [Manage Session Cookies](/docs/auth/admin/manage-cookies) for code - * samples and detailed documentation. + * See {@link https://firebase.google.com/docs/auth/admin/manage-cookies | Manage Session Cookies} + * for code samples and detailed documentation. * * @param idToken The Firebase ID token to exchange for a session * cookie. * @param sessionCookieOptions The session * cookie options which includes custom session duration. * - * @return A promise that resolves on success with the + * @returns A promise that resolves on success with the * created session cookie. */ public createSessionCookie( @@ -676,7 +673,8 @@ export abstract class BaseAuth { * `auth/session-cookie-revoked` error is thrown. If not specified the check is * not performed. * - * See [Verify Session Cookies](/docs/auth/admin/manage-cookies#verify_session_cookie_and_check_permissions) + * See {@link https://firebase.google.com/docs/auth/admin/manage-cookies#verify_session_cookie_and_check_permissions | + * Verify Session Cookies} * for code samples and detailed documentation * * @param sessionCookie The session cookie to verify. @@ -685,7 +683,7 @@ export abstract class BaseAuth { * check the `tokensValidAfterTime` time for the corresponding user. * When not specified, this additional check is not performed. * - * @return A promise fulfilled with the + * @returns A promise fulfilled with the * session cookie's decoded claims if the session cookie is valid; otherwise, * a rejected promise. */ @@ -707,7 +705,7 @@ export abstract class BaseAuth { /** * Generates the out of band email action link to reset a user's password. * The link is generated for the user with the specified email address. The - * optional {@link auth.ActionCodeSettings `ActionCodeSettings`} object + * optional {@link ActionCodeSettings} object * defines whether the link is to be handled by a mobile app or browser and the * additional state information to be passed in the deep link, etc. * @@ -751,7 +749,7 @@ export abstract class BaseAuth { * and accepts the Firebase Dynamic Links terms of service. * The Android package name and iOS bundle ID are respected only if they * are configured in the same Firebase Auth project. - * @return A promise that resolves with the generated link. + * @returns A promise that resolves with the generated link. */ public generatePasswordResetLink(email: string, actionCodeSettings?: ActionCodeSettings): Promise { return this.authRequestHandler.getEmailActionLink('PASSWORD_RESET', email, actionCodeSettings); @@ -759,8 +757,7 @@ export abstract class BaseAuth { /** * Generates the out of band email action link to verify the user's ownership - * of the specified email. The - * {@link auth.ActionCodeSettings `ActionCodeSettings`} object provided + * of the specified email. The {@link ActionCodeSettings} object provided * as an argument to this method defines whether the link is to be handled by a * mobile app or browser along with additional state information to be passed in * the deep link, etc. @@ -804,7 +801,7 @@ export abstract class BaseAuth { * and accepts the Firebase Dynamic Links terms of service. * The Android package name and iOS bundle ID are respected only if they * are configured in the same Firebase Auth project. - * @return A promise that resolves with the generated link. + * @returns A promise that resolves with the generated link. */ public generateEmailVerificationLink(email: string, actionCodeSettings?: ActionCodeSettings): Promise { return this.authRequestHandler.getEmailActionLink('VERIFY_EMAIL', email, actionCodeSettings); @@ -812,8 +809,7 @@ export abstract class BaseAuth { /** * Generates the out of band email action link to verify the user's ownership - * of the specified email. The - * {@link auth.ActionCodeSettings `ActionCodeSettings`} object provided + * of the specified email. The {@link ActionCodeSettings} object provided * as an argument to this method defines whether the link is to be handled by a * mobile app or browser along with additional state information to be passed in * the deep link, etc. @@ -857,7 +853,7 @@ export abstract class BaseAuth { * and accepts the Firebase Dynamic Links terms of service. * The Android package name and iOS bundle ID are respected only if they * are configured in the same Firebase Auth project. - * @return A promise that resolves with the generated link. + * @returns A promise that resolves with the generated link. */ public generateSignInWithEmailLink(email: string, actionCodeSettings: ActionCodeSettings): Promise { return this.authRequestHandler.getEmailActionLink('EMAIL_SIGNIN', email, actionCodeSettings); @@ -869,10 +865,10 @@ export abstract class BaseAuth { * * SAML and OIDC provider support requires Google Cloud's Identity Platform * (GCIP). To learn more about GCIP, including pricing and features, - * see the [GCIP documentation](https://cloud.google.com/identity-platform). + * see the {@link https://cloud.google.com/identity-platform | GCIP documentation}. * * @param options The provider config filter to apply. - * @return A promise that resolves with the list of provider configs meeting the + * @returns A promise that resolves with the list of provider configs meeting the * filter requirements. */ public listProviderConfigs(options: AuthProviderConfigFilter): Promise { @@ -926,11 +922,11 @@ export abstract class BaseAuth { * * SAML and OIDC provider support requires Google Cloud's Identity Platform * (GCIP). To learn more about GCIP, including pricing and features, - * see the [GCIP documentation](https://cloud.google.com/identity-platform). + * see the {@link https://cloud.google.com/identity-platform | GCIP documentation}. * * @param providerId The provider ID corresponding to the provider * config to return. - * @return A promise that resolves + * @returns A promise that resolves * with the configuration corresponding to the provided ID. */ public getProviderConfig(providerId: string): Promise { @@ -955,11 +951,11 @@ export abstract class BaseAuth { * * SAML and OIDC provider support requires Google Cloud's Identity Platform * (GCIP). To learn more about GCIP, including pricing and features, - * see the [GCIP documentation](https://cloud.google.com/identity-platform). + * see the {@link https://cloud.google.com/identity-platform | GCIP documentation}. * * @param providerId The provider ID corresponding to the provider * config to delete. - * @return A promise that resolves on completion. + * @returns A promise that resolves on completion. */ public deleteProviderConfig(providerId: string): Promise { if (OIDCConfig.isProviderId(providerId)) { @@ -978,12 +974,12 @@ export abstract class BaseAuth { * * SAML and OIDC provider support requires Google Cloud's Identity Platform * (GCIP). To learn more about GCIP, including pricing and features, - * see the [GCIP documentation](https://cloud.google.com/identity-platform). + * see the {@link https://cloud.google.com/identity-platform | GCIP documentation}. * * @param providerId The provider ID corresponding to the provider * config to update. * @param updatedConfig The updated configuration. - * @return A promise that resolves with the updated provider configuration. + * @returns A promise that resolves with the updated provider configuration. */ public updateProviderConfig( providerId: string, updatedConfig: UpdateAuthProviderRequest): Promise { @@ -1013,10 +1009,10 @@ export abstract class BaseAuth { * * SAML and OIDC provider support requires Google Cloud's Identity Platform * (GCIP). To learn more about GCIP, including pricing and features, - * see the [GCIP documentation](https://cloud.google.com/identity-platform). + * see the {@link https://cloud.google.com/identity-platform | GCIP documentation}. * * @param config The provider configuration to create. - * @return A promise that resolves with the created provider configuration. + * @returns A promise that resolves with the created provider configuration. */ public createProviderConfig(config: AuthProviderConfig): Promise { if (!validator.isNonNullObject(config)) { @@ -1046,7 +1042,7 @@ export abstract class BaseAuth { * @param decodedIdToken The JWT's decoded claims. * @param revocationErrorInfo The revocation error info to throw on revocation * detection. - * @return A Promise that will be fulfilled after a successful verification. + * @returns A Promise that will be fulfilled after a successful verification. */ private verifyDecodedJWTNotRevoked( decodedIdToken: DecodedIdToken, revocationErrorInfo: ErrorInfo): Promise { diff --git a/src/auth/identifier.ts b/src/auth/identifier.ts index 8db37c36b4..8bae483d1d 100644 --- a/src/auth/identifier.ts +++ b/src/auth/identifier.ts @@ -17,7 +17,7 @@ /** * Used for looking up an account by uid. * - * See `auth.getUsers()` + * See {@link BaseAuth.getUsers}. */ export interface UidIdentifier { uid: string; @@ -26,7 +26,7 @@ export interface UidIdentifier { /** * Used for looking up an account by email. * - * See `auth.getUsers()` + * See {@link BaseAuth.getUsers}. */ export interface EmailIdentifier { email: string; @@ -35,7 +35,7 @@ export interface EmailIdentifier { /** * Used for looking up an account by phone number. * - * See `auth.getUsers()` + * See {@link BaseAuth.getUsers}. */ export interface PhoneIdentifier { phoneNumber: string; @@ -44,7 +44,7 @@ export interface PhoneIdentifier { /** * Used for looking up an account by federated provider. * - * See `auth.getUsers()` + * See {@link BaseAuth.getUsers}. */ export interface ProviderIdentifier { providerId: string; diff --git a/src/auth/tenant-manager.ts b/src/auth/tenant-manager.ts index 2878ed907c..d3992fc2a1 100644 --- a/src/auth/tenant-manager.ts +++ b/src/auth/tenant-manager.ts @@ -29,14 +29,14 @@ import { DecodedIdToken } from './token-verifier'; /** * Interface representing the object returned from a - * {@link auth.TenantManager.listTenants `listTenants()`} + * {@link TenantManager.listTenants} * operation. * Contains the list of tenants for the current batch and the next page token if available. */ export interface ListTenantsResult { /** - * The list of {@link auth.Tenant `Tenant`} objects for the downloaded batch. + * The list of {@link Tenant} objects for the downloaded batch. */ tenants: Tenant[]; @@ -52,7 +52,7 @@ export interface ListTenantsResult { * * Multi-tenancy support requires Google Cloud's Identity Platform * (GCIP). To learn more about GCIP, including pricing and features, - * see the [GCIP documentation](https://cloud.google.com/identity-platform) + * see the {@link https://cloud.google.com/identity-platform | GCIP documentation}. * * Each tenant contains its own identity providers, settings and sets of users. * Using `TenantAwareAuth`, users for a specific tenant and corresponding OIDC/SAML @@ -61,7 +61,7 @@ export interface ListTenantsResult { * tenant. * * `TenantAwareAuth` instances for a specific `tenantId` can be instantiated by calling - * `auth.tenantManager().authForTenant(tenantId)`. + * {@link TenantManager.authForTenant}. */ export class TenantAwareAuth extends BaseAuth { @@ -169,7 +169,7 @@ export class TenantManager { * * @param tenantId The tenant ID whose `TenantAwareAuth` instance is to be returned. * - * @return The `TenantAwareAuth` instance corresponding to this tenant identifier. + * @returns The `TenantAwareAuth` instance corresponding to this tenant identifier. */ public authForTenant(tenantId: string): TenantAwareAuth { if (!validator.isNonEmptyString(tenantId)) { @@ -186,7 +186,7 @@ export class TenantManager { * * @param tenantId The tenant identifier corresponding to the tenant whose data to fetch. * - * @return A promise fulfilled with the tenant configuration to the provided `tenantId`. + * @returns A promise fulfilled with the tenant configuration to the provided `tenantId`. */ public getTenant(tenantId: string): Promise { return this.authRequestHandler.getTenant(tenantId) @@ -205,7 +205,7 @@ export class TenantManager { * @param pageToken The next page token. If not specified, returns * tenants starting without any offset. * - * @return A promise that resolves with + * @returns A promise that resolves with * a batch of downloaded tenants and the next page token. */ public listTenants( @@ -237,7 +237,7 @@ export class TenantManager { * * @param tenantId The `tenantId` corresponding to the tenant to delete. * - * @return An empty promise fulfilled once the tenant has been deleted. + * @returns An empty promise fulfilled once the tenant has been deleted. */ public deleteTenant(tenantId: string): Promise { return this.authRequestHandler.deleteTenant(tenantId); @@ -250,7 +250,7 @@ export class TenantManager { * * @param tenantOptions The properties to set on the new tenant configuration to be created. * - * @return A promise fulfilled with the tenant configuration corresponding to the newly + * @returns A promise fulfilled with the tenant configuration corresponding to the newly * created tenant. */ public createTenant(tenantOptions: CreateTenantRequest): Promise { @@ -266,7 +266,7 @@ export class TenantManager { * @param tenantId The `tenantId` corresponding to the tenant to delete. * @param tenantOptions The properties to update on the provided tenant. * - * @return A promise fulfilled with the update tenant data. + * @returns A promise fulfilled with the update tenant data. */ public updateTenant(tenantId: string, tenantOptions: UpdateTenantRequest): Promise { return this.authRequestHandler.updateTenant(tenantId, tenantOptions) diff --git a/src/auth/tenant.ts b/src/auth/tenant.ts index c6359a1e85..6c5577bda2 100644 --- a/src/auth/tenant.ts +++ b/src/auth/tenant.ts @@ -86,7 +86,7 @@ export interface TenantServerResponse { * * Multi-tenancy support requires Google Cloud's Identity Platform * (GCIP). To learn more about GCIP, including pricing and features, - * see the [GCIP documentation](https://cloud.google.com/identity-platform) + * see the {@link https://cloud.google.com/identity-platform | GCIP documentation}. * * Before multi-tenancy can be used on a Google Cloud Identity Platform project, * tenants must be allowed on that project via the Cloud Console UI. @@ -128,7 +128,7 @@ export class Tenant { * * @param tenantOptions The properties to convert to a server request. * @param createRequest Whether this is a create request. - * @return The equivalent server request. + * @returns The equivalent server request. * * @internal */ @@ -158,8 +158,8 @@ export class Tenant { /** * Returns the tenant ID corresponding to the resource name if available. * - * @param {string} resourceName The server side resource name - * @return {?string} The tenant ID corresponding to the resource, null otherwise. + * @param resourceName The server side resource name + * @returns The tenant ID corresponding to the resource, null otherwise. * * @internal */ @@ -282,7 +282,9 @@ export class Tenant { } /** - * @return A JSON-serializable representation of this object. + * Returns a JSON-serializable representation of this object. + * + * @returns A JSON-serializable representation of this object. */ public toJSON(): object { const json = { diff --git a/src/auth/token-generator.ts b/src/auth/token-generator.ts index a9c03130c6..d8e6e1962d 100644 --- a/src/auth/token-generator.ts +++ b/src/auth/token-generator.ts @@ -54,14 +54,14 @@ export interface CryptoSigner { * Cryptographically signs a buffer of data. * * @param {Buffer} buffer The data to be signed. - * @return {Promise} A promise that resolves with the raw bytes of a signature. + * @returns {Promise} A promise that resolves with the raw bytes of a signature. */ sign(buffer: Buffer): Promise; /** * Returns the ID of the service account used to sign tokens. * - * @return {Promise} A promise that resolves with a service account ID. + * @returns {Promise} A promise that resolves with a service account ID. */ getAccountId(): Promise; } @@ -259,7 +259,7 @@ export class EmulatedSigner implements CryptoSigner { * account credential, creates a ServiceAccountSigner. Otherwise creates an IAMSigner. * * @param {FirebaseApp} app A FirebaseApp instance. - * @return {CryptoSigner} A CryptoSigner instance. + * @returns {CryptoSigner} A CryptoSigner instance. */ export function cryptoSignerFromApp(app: App): CryptoSigner { const credential = app.options.credential; @@ -303,7 +303,7 @@ export class FirebaseTokenGenerator { * @param uid The user ID to use for the generated Firebase Auth Custom token. * @param developerClaims Optional developer claims to include in the generated Firebase * Auth Custom token. - * @return A Promise fulfilled with a Firebase Auth Custom token signed with a + * @returns A Promise fulfilled with a Firebase Auth Custom token signed with a * service account key and containing the provided payload. */ public createCustomToken(uid: string, developerClaims?: {[key: string]: any}): Promise { @@ -374,7 +374,7 @@ export class FirebaseTokenGenerator { * Returns whether or not the provided developer claims are valid. * * @param {object} [developerClaims] Optional developer claims to validate. - * @return {boolean} True if the provided claims are valid; otherwise, false. + * @returns {boolean} True if the provided claims are valid; otherwise, false. */ private isDeveloperClaimsValid_(developerClaims?: object): boolean { if (typeof developerClaims === 'undefined') { diff --git a/src/auth/token-verifier.ts b/src/auth/token-verifier.ts index b07ad29c14..4a88420f5a 100644 --- a/src/auth/token-verifier.ts +++ b/src/auth/token-verifier.ts @@ -299,7 +299,7 @@ export class FirebaseTokenVerifier { * * @param jwtToken The Firebase Auth JWT token to verify. * @param isEmulator Whether to accept Auth Emulator tokens. - * @return A promise fulfilled with the decoded claims of the Firebase Auth ID token. + * @returns A promise fulfilled with the decoded claims of the Firebase Auth ID token. */ public verifyJWT(jwtToken: string, isEmulator = false): Promise { if (!validator.isString(jwtToken)) { @@ -460,7 +460,7 @@ export class FirebaseTokenVerifier { * * @internal * @param app Firebase app instance. - * @return FirebaseTokenVerifier + * @returns FirebaseTokenVerifier */ export function createIdTokenVerifier(app: App): FirebaseTokenVerifier { return new FirebaseTokenVerifier( @@ -476,7 +476,7 @@ export function createIdTokenVerifier(app: App): FirebaseTokenVerifier { * * @internal * @param app Firebase app instance. - * @return FirebaseTokenVerifier + * @returns FirebaseTokenVerifier */ export function createSessionCookieVerifier(app: App): FirebaseTokenVerifier { return new FirebaseTokenVerifier( diff --git a/src/auth/user-import-builder.ts b/src/auth/user-import-builder.ts index c0e151abaa..811e7c9963 100644 --- a/src/auth/user-import-builder.ts +++ b/src/auth/user-import-builder.ts @@ -319,7 +319,7 @@ export type ValidatorFunction = (data: UploadAccountUser) => void; /** * Converts a client format second factor object to server format. * @param multiFactorInfo The client format second factor. - * @return The corresponding AuthFactorInfo server request format. + * @returns The corresponding AuthFactorInfo server request format. */ export function convertMultiFactorInfoToServerFormat(multiFactorInfo: UpdateMultiFactorInfoRequest): AuthFactorInfo { let enrolledAt; @@ -366,7 +366,7 @@ function isPhoneFactor(multiFactorInfo: UpdateMultiFactorInfoRequest): /** * @param {any} obj The object to check for number field within. * @param {string} key The entry key. - * @return {number} The corresponding number if available. Otherwise, NaN. + * @returns {number} The corresponding number if available. Otherwise, NaN. */ function getNumberField(obj: any, key: string): number { if (typeof obj[key] !== 'undefined' && obj[key] !== null) { @@ -381,7 +381,7 @@ function getNumberField(obj: any, key: string): number { * fields are provided. * @param {UserImportRecord} user The UserImportRecord to conver to UploadAccountUser. * @param {ValidatorFunction=} userValidator The user validator function. - * @return {UploadAccountUser} The corresponding UploadAccountUser to return. + * @returns {UploadAccountUser} The corresponding UploadAccountUser to return. */ function populateUploadAccountUser( user: UserImportRecord, userValidator?: ValidatorFunction): UploadAccountUser { @@ -497,7 +497,7 @@ export class UserImportBuilder { /** * Returns the corresponding constructed uploadAccount request. - * @return {UploadAccountRequest} The constructed uploadAccount request. + * @returns {UploadAccountRequest} The constructed uploadAccount request. */ public buildRequest(): UploadAccountRequest { const users = this.validatedUsers.map((user) => { @@ -509,7 +509,7 @@ export class UserImportBuilder { /** * Populates the UserImportResult using the client side detected errors and the server * side returned errors. - * @return {UserImportResult} The user import result based on the returned failed + * @returns {UserImportResult} The user import result based on the returned failed * uploadAccount response. */ public buildResponse( @@ -545,7 +545,7 @@ export class UserImportBuilder { * Throws an error whenever an invalid or missing options is detected. * @param {UserImportOptions} options The UserImportOptions. * @param {boolean} requiresHashOptions Whether to require hash options. - * @return {UploadAccountOptions} The populated UploadAccount options. + * @returns {UploadAccountOptions} The populated UploadAccount options. */ private populateOptions( options: UserImportOptions | undefined, requiresHashOptions: boolean): UploadAccountOptions { @@ -733,7 +733,7 @@ export class UserImportBuilder { * @param {UserImportRecord[]} users The UserImportRecords to convert to UnploadAccountUser * objects. * @param {ValidatorFunction=} userValidator The user validator function. - * @return {UploadAccountUser[]} The populated uploadAccount users. + * @returns {UploadAccountUser[]} The populated uploadAccount users. */ private populateUsers( users: UserImportRecord[], userValidator?: ValidatorFunction): UploadAccountUser[] { diff --git a/src/auth/user-record.ts b/src/auth/user-record.ts index da55540b56..49c21b4768 100644 --- a/src/auth/user-record.ts +++ b/src/auth/user-record.ts @@ -28,8 +28,8 @@ const B64_REDACTED = Buffer.from('REDACTED').toString('base64'); /** * Parses a time stamp string or number and returns the corresponding date if valid. * - * @param {any} time The unix timestamp string or number in milliseconds. - * @return {string} The corresponding date as a UTC string, if valid. Otherwise, null. + * @param time The unix timestamp string or number in milliseconds. + * @returns The corresponding date as a UTC string, if valid. Otherwise, null. */ function parseDate(time: any): string | null { try { @@ -141,7 +141,9 @@ export abstract class MultiFactorInfo { } /** - * @return A JSON-serializable representation of this object. + * Returns a JSON-serializable representation of this object. + * + * @returns A JSON-serializable representation of this object. */ public toJSON(): object { return { @@ -156,7 +158,7 @@ export abstract class MultiFactorInfo { * Returns the factor ID based on the response provided. * * @param response The server side response. - * @return The multi-factor ID associated with the provided response. If the response is + * @returns The multi-factor ID associated with the provided response. If the response is * not associated with any known multi-factor ID, null is returned. * * @internal @@ -228,7 +230,7 @@ export class PhoneMultiFactorInfo extends MultiFactorInfo { * Returns the factor ID based on the response provided. * * @param response The server side response. - * @return The multi-factor ID associated with the provided response. If the response is + * @returns The multi-factor ID associated with the provided response. If the response is * not associated with any known multi-factor ID, null is returned. * * @internal @@ -276,7 +278,9 @@ export class MultiFactorSettings { } /** - * @return A JSON-serializable representation of this multi-factor object. + * Returns a JSON-serializable representation of this multi-factor object. + * + * @returns A JSON-serializable representation of this multi-factor object. */ public toJSON(): object { return { @@ -325,7 +329,9 @@ export class UserMetadata { } /** - * @return A JSON-serializable representation of this object. + * Returns a JSON-serializable representation of this object. + * + * @returns A JSON-serializable representation of this object. */ public toJSON(): object { return { @@ -395,7 +401,9 @@ export class UserInfo { } /** - * @return A JSON-serializable representation of this object. + * Returns a JSON-serializable representation of this object. + * + * @returns A JSON-serializable representation of this object. */ public toJSON(): object { return { @@ -466,7 +474,7 @@ export class UserRecord { * when uploading this user, as is typical when migrating from another Auth * system, this will be an empty string. If no password is set, this is * null. This is only available when the user is obtained from - * {@link auth.Auth.listUsers `listUsers()`}. + * {@link BaseAuth.listUsers}. */ public readonly passwordHash?: string; @@ -475,16 +483,14 @@ export class UserRecord { * algorithm (SCRYPT) is used. If a different hashing algorithm had been used to * upload this user, typical when migrating from another Auth system, this will * be an empty string. If no password is set, this is null. This is only - * available when the user is obtained from - * {@link auth.Auth.listUsers `listUsers()`}. + * available when the user is obtained from {@link BaseAuth.listUsers}. */ public readonly passwordSalt?: string; /** * The user's custom claims object if available, typically used to define * user roles and propagated to an authenticated user's ID token. - * This is set via - * {@link auth.Auth.setCustomUserClaims `setCustomUserClaims()`} + * This is set via {@link BaseAuth.setCustomUserClaims} */ public readonly customClaims?: {[key: string]: any}; @@ -496,7 +502,7 @@ export class UserRecord { /** * The date the user's tokens are valid after, formatted as a UTC string. * This is updated every time the user's refresh token are revoked either - * from the {@link auth.Auth.revokeRefreshTokens `revokeRefreshTokens()`} + * from the {@link BaseAuth.revokeRefreshTokens} * API or from the Firebase Auth backend on big account changes (password * resets, password or email updates, etc). */ @@ -565,7 +571,9 @@ export class UserRecord { } /** - * @return A JSON-serializable representation of this object. + * Returns a JSON-serializable representation of this object. + * + * @returns A JSON-serializable representation of this object. */ public toJSON(): object { const json: any = { diff --git a/src/credential/index.ts b/src/credential/index.ts index fd20d0ab9f..7cc49758e8 100644 --- a/src/credential/index.ts +++ b/src/credential/index.ts @@ -37,22 +37,16 @@ export namespace credential { /** * Returns a credential created from the - * {@link - * https://developers.google.com/identity/protocols/application-default-credentials - * Google Application Default Credentials} + * {@link https://developers.google.com/identity/protocols/application-default-credentials | + * Google Application Default Credentials} * that grants admin access to Firebase services. This credential can be used - * in the call to - * {@link - * https://firebase.google.com/docs/reference/admin/node/admin#.initializeApp - * `admin.initializeApp()`}. + * in the call to {@link firebase-admin.app#initializeApp}. * * Google Application Default Credentials are available on any Google * infrastructure, such as Google App Engine and Google Compute Engine. * * See - * {@link - * https://firebase.google.com/docs/admin/setup#initialize_the_sdk - * Initialize the SDK} + * {@link https://firebase.google.com/docs/admin/setup#initialize_the_sdk | Initialize the SDK} * for more details. * * @example @@ -63,10 +57,10 @@ export namespace credential { * }); * ``` * - * @param {!Object=} httpAgent Optional [HTTP Agent](https://nodejs.org/api/http.html#http_class_http_agent) + * @param httpAgent Optional {@link https://nodejs.org/api/http.html#http_class_http_agent | HTTP Agent} * to be used when retrieving access tokens from Google token servers. * - * @return {!admin.credential.Credential} A credential authenticated via Google + * @returns A credential authenticated via Google * Application Default Credentials that can be used to initialize an app. */ export const applicationDefault = applicationDefaultFn; @@ -74,15 +68,10 @@ export namespace credential { /** * Returns a credential created from the provided service account that grants * admin access to Firebase services. This credential can be used in the call - * to - * {@link - * https://firebase.google.com/docs/reference/admin/node/admin#.initializeApp - * `admin.initializeApp()`}. + * to {@link firebase-admin.app#initializeApp}. * * See - * {@link - * https://firebase.google.com/docs/admin/setup#initialize_the_sdk - * Initialize the SDK} + * {@link https://firebase.google.com/docs/admin/setup#initialize_the_sdk | Initialize the SDK} * for more details. * * @example @@ -110,10 +99,10 @@ export namespace credential { * * @param serviceAccountPathOrObject The path to a service * account key JSON file or an object representing a service account key. - * @param httpAgent Optional [HTTP Agent](https://nodejs.org/api/http.html#http_class_http_agent) + * @param httpAgent Optional {@link https://nodejs.org/api/http.html#http_class_http_agent | HTTP Agent} * to be used when retrieving access tokens from Google token servers. * - * @return A credential authenticated via the + * @returns A credential authenticated via the * provided service account that can be used to initialize an app. */ export const cert = certFn; @@ -121,15 +110,10 @@ export namespace credential { /** * Returns a credential created from the provided refresh token that grants * admin access to Firebase services. This credential can be used in the call - * to - * {@link - * https://firebase.google.com/docs/reference/admin/node/admin#.initializeApp - * `admin.initializeApp()`}. + * to {@link firebase-admin.app#initializeApp}. * * See - * {@link - * https://firebase.google.com/docs/admin/setup#initialize_the_sdk - * Initialize the SDK} + * {@link https://firebase.google.com/docs/admin/setup#initialize_the_sdk | Initialize the SDK} * for more details. * * @example @@ -145,10 +129,10 @@ export namespace credential { * @param refreshTokenPathOrObject The path to a Google * OAuth2 refresh token JSON file or an object representing a Google OAuth2 * refresh token. - * @param httpAgent Optional [HTTP Agent](https://nodejs.org/api/http.html#http_class_http_agent) + * @param httpAgent Optional {@link https://nodejs.org/api/http.html#http_class_http_agent | HTTP Agent} * to be used when retrieving access tokens from Google token servers. * - * @return A credential authenticated via the + * @returns A credential authenticated via the * provided service account that can be used to initialize an app. */ export const refreshToken = refreshTokenFn; diff --git a/src/database/database-namespace.ts b/src/database/database-namespace.ts index b8882f8997..a6c1f4716e 100644 --- a/src/database/database-namespace.ts +++ b/src/database/database-namespace.ts @@ -19,14 +19,12 @@ import { App } from '../app'; import { Database as TDatabase } from './database'; /** - * Gets the {@link database.Database `Database`} service for the default + * Gets the {@link firebase-admin.database#Database} service for the default * app or a given app. * * `admin.database()` can be called with no arguments to access the default - * app's {@link database.Database `Database`} service or as - * `admin.database(app)` to access the - * {@link database.Database `Database`} service associated with a specific - * app. + * app's `Database` service or as `admin.database(app)` to access the + * `Database` service associated with a specific app. * * `admin.database` is also a namespace that can be used to access global * constants and methods associated with the `Database` service. @@ -46,7 +44,7 @@ import { Database as TDatabase } from './database'; * @param App whose `Database` service to * return. If not provided, the default `Database` service will be returned. * - * @return The default `Database` service if no app + * @returns The default `Database` service if no app * is provided or the `Database` service associated with the provided app. */ export declare function database(app?: App): database.Database; @@ -64,7 +62,7 @@ export namespace database { export declare const enableLogging: typeof rtdb.enableLogging; /** - * [`ServerValue`](https://firebase.google.com/docs/reference/js/firebase.database.ServerValue) + * {@link https://firebase.google.com/docs/reference/js/firebase.database.ServerValue | ServerValue} * module from the `@firebase/database` package. */ export declare const ServerValue: rtdb.ServerValue; diff --git a/src/database/database.ts b/src/database/database.ts index e3ff53b010..4d5275f405 100644 --- a/src/database/database.ts +++ b/src/database/database.ts @@ -32,7 +32,7 @@ export interface Database extends FirebaseDatabase { * Gets the currently applied security rules as a string. The return value consists of * the rules source including comments. * - * @return A promise fulfilled with the rules as a raw string. + * @returns A promise fulfilled with the rules as a raw string. */ getRules(): Promise; @@ -40,7 +40,7 @@ export interface Database extends FirebaseDatabase { * Gets the currently applied security rules as a parsed JSON object. Any comments in * the original source are stripped away. * - * @return A promise fulfilled with the parsed rules object. + * @returns A promise fulfilled with the parsed rules object. */ getRulesJSON(): Promise; @@ -49,7 +49,7 @@ export interface Database extends FirebaseDatabase { * specified as a string or a Buffer, it may include comments. * * @param source Source of the rules to apply. Must not be `null` or empty. - * @return Resolves when the rules are set on the Realtime Database. + * @returns Resolves when the rules are set on the Realtime Database. */ setRules(source: string | Buffer | object): Promise; } @@ -102,7 +102,7 @@ export class DatabaseService { /** * Returns the app associated with this DatabaseService instance. * - * @return The app associated with this DatabaseService instance. + * @returns The app associated with this DatabaseService instance. */ get app(): App { return this.appInternal; @@ -212,7 +212,7 @@ class DatabaseRulesClient { * Gets the currently applied security rules as a string. The return value consists of * the rules source including comments. * - * @return A promise fulfilled with the rules as a raw string. + * @returns A promise fulfilled with the rules as a raw string. */ public getRules(): Promise { const req: HttpRequestConfig = { @@ -235,7 +235,7 @@ class DatabaseRulesClient { * Gets the currently applied security rules as a parsed JSON object. Any comments in * the original source are stripped away. * - * @return {Promise} A promise fulfilled with the parsed rules source. + * @returns {Promise} A promise fulfilled with the parsed rules source. */ public getRulesJSON(): Promise { const req: HttpRequestConfig = { @@ -258,7 +258,7 @@ class DatabaseRulesClient { * * @param {string|Buffer|object} source Source of the rules to apply. Must not be `null` * or empty. - * @return {Promise} Resolves when the rules are set on the Database. + * @returns {Promise} Resolves when the rules are set on the Database. */ public setRules(source: string | Buffer | object): Promise { if (!validator.isNonEmptyString(source) && diff --git a/src/database/index.ts b/src/database/index.ts index 060a68c679..e81ba68e60 100644 --- a/src/database/index.ts +++ b/src/database/index.ts @@ -35,13 +35,13 @@ export { } from '@firebase/database-types'; /** - * [`enableLogging`](https://firebase.google.com/docs/reference/js/firebase.database#enablelogging) + * {@link https://firebase.google.com/docs/reference/js/firebase.database#enablelogging | enableLogging} * function from the `@firebase/database` package. */ export const enableLogging: typeof rtdb.enableLogging = enableLoggingFunc; /** - * [`ServerValue`](https://firebase.google.com/docs/reference/js/firebase.database.ServerValue) + * {@link https://firebase.google.com/docs/reference/js/firebase.database.ServerValue | ServerValue} * module from the `@firebase/database` package. */ export const ServerValue: rtdb.ServerValue = serverValueConst; @@ -71,7 +71,7 @@ export const ServerValue: rtdb.ServerValue = serverValueConst; * @param App whose `Database` service to * return. If not provided, the default `Database` service will be returned. * - * @return The default `Database` service if no app + * @returns The default `Database` service if no app * is provided or the `Database` service associated with the provided app. */ export function getDatabase(app?: App): Database { @@ -103,7 +103,7 @@ export function getDatabase(app?: App): Database { * @param App whose `Database` service to * return. If not provided, the default `Database` service will be returned. * - * @return The default `Database` service if no app + * @returns The default `Database` service if no app * is provided or the `Database` service associated with the provided app. */ export function getDatabaseWithUrl(url: string, app?: App): Database { diff --git a/src/firestore/firestore-internal.ts b/src/firestore/firestore-internal.ts index 7c4df98242..b883251d41 100644 --- a/src/firestore/firestore-internal.ts +++ b/src/firestore/firestore-internal.ts @@ -36,7 +36,7 @@ export class FirestoreService { /** * Returns the app associated with this Storage instance. * - * @return The app associated with this Storage instance. + * @returns The app associated with this Storage instance. */ get app(): App { return this.appInternal; diff --git a/src/instance-id/index.ts b/src/instance-id/index.ts index c6ce147f80..fdc44e8341 100644 --- a/src/instance-id/index.ts +++ b/src/instance-id/index.ts @@ -21,14 +21,11 @@ import { InstanceId } from './instance-id'; export { InstanceId }; /** - * Gets the {@link InstanceId `InstanceId`} service for the - * default app or a given app. + * Gets the {@link InstanceId} service for the default app or a given app. * * `getInstanceId()` can be called with no arguments to access the default - * app's {@link InstanceId `InstanceId`} service or as - * `getInstanceId(app)` to access the - * {@link InstanceId `InstanceId`} service associated with a - * specific app. + * app's `InstanceId` service or as `getInstanceId(app)` to access the + * `InstanceId` service associated with a specific app. * * @example * ```javascript @@ -46,7 +43,7 @@ export { InstanceId }; * return. If not provided, the default `InstanceId` service will be * returned. * - * @return The default `InstanceId` service if + * @returns The default `InstanceId` service if * no app is provided or the `InstanceId` service associated with the * provided app. */ diff --git a/src/instance-id/instance-id-namespace.ts b/src/instance-id/instance-id-namespace.ts index 74b367a595..f814cd874e 100644 --- a/src/instance-id/instance-id-namespace.ts +++ b/src/instance-id/instance-id-namespace.ts @@ -2,14 +2,12 @@ import { App } from '../app/index'; import { InstanceId as TInstanceId } from './instance-id'; /** - * Gets the {@link instanceId.InstanceId `InstanceId`} service for the + * Gets the {@link firebase-admin.instance-id#InstanceId} service for the * default app or a given app. * * `admin.instanceId()` can be called with no arguments to access the default - * app's {@link instanceId.InstanceId `InstanceId`} service or as - * `admin.instanceId(app)` to access the - * {@link instanceId.InstanceId `InstanceId`} service associated with a - * specific app. + * app's `InstanceId` service or as `admin.instanceId(app)` to access the + * `InstanceId` service associated with a specific app. * * @example * ```javascript @@ -27,7 +25,7 @@ import { InstanceId as TInstanceId } from './instance-id'; * return. If not provided, the default `InstanceId` service will be * returned. * - * @return The default `InstanceId` service if + * @returns The default `InstanceId` service if * no app is provided or the `InstanceId` service associated with the * provided app. */ diff --git a/src/instance-id/instance-id-request-internal.ts b/src/instance-id/instance-id-request-internal.ts index 1ef9125744..52441b84ee 100644 --- a/src/instance-id/instance-id-request-internal.ts +++ b/src/instance-id/instance-id-request-internal.ts @@ -76,8 +76,8 @@ export class FirebaseInstanceIdRequestHandler { /** * Invokes the request handler based on the API settings object passed. * - * @param {ApiSettings} apiSettings The API endpoint settings to apply to request and response. - * @return {Promise} A promise that resolves when the request is complete. + * @param apiSettings The API endpoint settings to apply to request and response. + * @returns A promise that resolves when the request is complete. */ private invokeRequestHandler(apiSettings: ApiSettings): Promise { return this.getPathPrefix() diff --git a/src/instance-id/instance-id.ts b/src/instance-id/instance-id.ts index 0e7bd0a66a..eb4492b2a1 100644 --- a/src/instance-id/instance-id.ts +++ b/src/instance-id/instance-id.ts @@ -51,12 +51,13 @@ export class InstanceId { * Note that Google Analytics for Firebase uses its own form of Instance ID to * keep track of analytics data. Therefore deleting a Firebase Instance ID does * not delete Analytics data. See - * [Delete an Instance ID](/support/privacy/manage-iids#delete_an_instance_id) + * {@link https://firebase.google.com/support/privacy/manage-iids#delete_an_instance_id | + * Delete an Instance ID} * for more information. * * @param instanceId The instance ID to be deleted. * - * @return A promise fulfilled when the instance ID is deleted. + * @returns A promise fulfilled when the instance ID is deleted. */ public deleteInstanceId(instanceId: string): Promise { return this.requestHandler.deleteInstanceId(instanceId) @@ -68,7 +69,7 @@ export class InstanceId { /** * Returns the app associated with this InstanceId instance. * - * @return The app associated with this InstanceId instance. + * @returns The app associated with this InstanceId instance. */ get app(): App { return this.app_; diff --git a/src/machine-learning/index.ts b/src/machine-learning/index.ts index 279273d301..e10fb222ac 100644 --- a/src/machine-learning/index.ts +++ b/src/machine-learning/index.ts @@ -33,34 +33,31 @@ export { } from './machine-learning-api-client'; /** - * Gets the {@link machineLearning.MachineLearning `MachineLearning`} service for the - * default app or a given app. + * Gets the {@link MachineLearning} service for the default app or a given app. * * `getMachineLearning()` can be called with no arguments to access the - * default app's {@link machineLearning.MachineLearning - * `MachineLearning`} service or as `getMachineLearning(app)` to access - * the {@link machineLearning.MachineLearning `MachineLearning`} - * service associated with a specific app. - * - * @example - * ```javascript - * // Get the MachineLearning service for the default app - * const defaultMachineLearning = getMachineLearning(); - * ``` - * - * @example - * ```javascript - * // Get the MachineLearning service for a given app - * const otherMachineLearning = getMachineLearning(otherApp); - * ``` - * - * @param app Optional app whose `MachineLearning` service to - * return. If not provided, the default `MachineLearning` service - * will be returned. - * - * @return The default `MachineLearning` service if no app is provided or the - * `MachineLearning` service associated with the provided app. - */ + * default app's {`MachineLearning` service or as `getMachineLearning(app)` to access + * the `MachineLearning` service associated with a specific app. + * + * @example + * ```javascript + * // Get the MachineLearning service for the default app + * const defaultMachineLearning = getMachineLearning(); + * ``` + * + * @example + * ```javascript + * // Get the MachineLearning service for a given app + * const otherMachineLearning = getMachineLearning(otherApp); + * ``` + * + * @param app Optional app whose `MachineLearning` service to + * return. If not provided, the default `MachineLearning` service + * will be returned. + * + * @returns The default `MachineLearning` service if no app is provided or the + * `MachineLearning` service associated with the provided app. + */ export function getMachineLearning(app?: App): MachineLearning { if (typeof app === 'undefined') { app = getApp(); diff --git a/src/machine-learning/machine-learning-namespace.ts b/src/machine-learning/machine-learning-namespace.ts index 021b6ca6aa..d16b4d1a0c 100644 --- a/src/machine-learning/machine-learning-namespace.ts +++ b/src/machine-learning/machine-learning-namespace.ts @@ -30,14 +30,12 @@ import { } from './machine-learning-api-client'; /** - * Gets the {@link machineLearning.MachineLearning `MachineLearning`} service for the + * Gets the {@link firebase-admin.machine-learning#MachineLearning} service for the * default app or a given app. * * `admin.machineLearning()` can be called with no arguments to access the - * default app's {@link machineLearning.MachineLearning - * `MachineLearning`} service or as `admin.machineLearning(app)` to access - * the {@link machineLearning.MachineLearning `MachineLearning`} - * service associated with a specific app. + * default app's `MachineLearning` service or as `admin.machineLearning(app)` to access + * the `MachineLearning` service associated with a specific app. * * @example * ```javascript @@ -55,7 +53,7 @@ import { * return. If not provided, the default `MachineLearning` service * will be returned. * - * @return The default `MachineLearning` service if no app is provided or the + * @returns The default `MachineLearning` service if no app is provided or the * `MachineLearning` service associated with the provided app. */ export declare function machineLearning(app?: App): machineLearning.MachineLearning; diff --git a/src/machine-learning/machine-learning.ts b/src/machine-learning/machine-learning.ts index 5c60438adf..849aad7546 100644 --- a/src/machine-learning/machine-learning.ts +++ b/src/machine-learning/machine-learning.ts @@ -84,7 +84,7 @@ export class MachineLearning { } /** - * The {@link app.App} associated with the current `MachineLearning` + * The {@link firebase-admin.app#App} associated with the current `MachineLearning` * service instance. */ public get app(): App { @@ -96,7 +96,7 @@ export class MachineLearning { * * @param model The model to create. * - * @return A Promise fulfilled with the created model. + * @returns A Promise fulfilled with the created model. */ public createModel(model: ModelOptions): Promise { return this.signUrlIfPresent(model) @@ -111,7 +111,7 @@ export class MachineLearning { * @param modelId The ID of the model to update. * @param model The model fields to update. * - * @return A Promise fulfilled with the updated model. + * @returns A Promise fulfilled with the updated model. */ public updateModel(modelId: string, model: ModelOptions): Promise { const updateMask = utils.generateUpdateMask(model); @@ -128,7 +128,7 @@ export class MachineLearning { * * @param modelId The ID of the model to publish. * - * @return A Promise fulfilled with the published model. + * @returns A Promise fulfilled with the published model. */ public publishModel(modelId: string): Promise { return this.setPublishStatus(modelId, true); @@ -139,7 +139,7 @@ export class MachineLearning { * * @param modelId The ID of the model to unpublish. * - * @return A Promise fulfilled with the unpublished model. + * @returns A Promise fulfilled with the unpublished model. */ public unpublishModel(modelId: string): Promise { return this.setPublishStatus(modelId, false); @@ -150,7 +150,7 @@ export class MachineLearning { * * @param modelId The ID of the model to get. * - * @return A Promise fulfilled with the model object. + * @returns A Promise fulfilled with the model object. */ public getModel(modelId: string): Promise { return this.client.getModel(modelId) @@ -162,7 +162,7 @@ export class MachineLearning { * * @param options The listing options. * - * @return A promise that + * @returns A promise that * resolves with the current (filtered) list of models and the next page * token. For the last page, an empty list of models and no page token * are returned. @@ -369,7 +369,7 @@ export class Model { * @param maxTimeMillis The maximum time in milliseconds to wait. * If not specified, a default maximum of 2 minutes is used. * - * @return A promise that resolves when the model is unlocked + * @returns A promise that resolves when the model is unlocked * or the maximum wait time has passed. */ public waitForUnlocked(maxTimeMillis?: number): Promise { diff --git a/src/messaging/batch-request-internal.ts b/src/messaging/batch-request-internal.ts index 0c6995a874..0e79af4c79 100644 --- a/src/messaging/batch-request-internal.ts +++ b/src/messaging/batch-request-internal.ts @@ -56,8 +56,8 @@ export class BatchRequestClient { * Sends the given array of sub requests as a single batch, and parses the results into an array * of HttpResponse objects. * - * @param {SubRequest[]} requests An array of sub requests to send. - * @return {Promise} A promise that resolves when the send operation is complete. + * @param requests An array of sub requests to send. + * @returns A promise that resolves when the send operation is complete. */ public send(requests: SubRequest[]): Promise { requests = requests.map((req) => { @@ -100,10 +100,10 @@ export class BatchRequestClient { * API, sets the content-type header to application/http, and the content-transfer-encoding to * binary. * - * @param {SubRequest} request A sub request that will be used to populate the part. - * @param {string} boundary Multipart boundary string. - * @param {number} idx An index number that is used to set the content-id header. - * @return {string} The part as a string that can be included in the HTTP body. + * @param request A sub request that will be used to populate the part. + * @param boundary Multipart boundary string. + * @param idx An index number that is used to set the content-id header. + * @returns The part as a string that can be included in the HTTP body. */ function createPart(request: SubRequest, boundary: string, idx: number): string { const serializedRequest: string = serializeSubRequest(request); @@ -122,8 +122,8 @@ function createPart(request: SubRequest, boundary: string, idx: number): string * format of the string is the wire format of a typical HTTP request, consisting of a header and a * body. * - * @param request {SubRequest} The sub request to be serialized. - * @return {string} String representation of the SubRequest. + * @param request The sub request to be serialized. + * @returns String representation of the SubRequest. */ function serializeSubRequest(request: SubRequest): string { const requestBody: string = JSON.stringify(request.body); diff --git a/src/messaging/index.ts b/src/messaging/index.ts index b64559e9f7..9d4cb990ae 100644 --- a/src/messaging/index.ts +++ b/src/messaging/index.ts @@ -61,14 +61,11 @@ export { } from './messaging-api'; /** - * Gets the {@link messaging.Messaging `Messaging`} service for the - * default app or a given app. + * Gets the {@link Messaging} service for the default app or a given app. * * `admin.messaging()` can be called with no arguments to access the default - * app's {@link messaging.Messaging `Messaging`} service or as - * `admin.messaging(app)` to access the - * {@link messaging.Messaging `Messaging`} service associated with a - * specific app. + * app's `Messaging` service or as `admin.messaging(app)` to access the + * `Messaging` service associated with aspecific app. * * @example * ```javascript @@ -85,7 +82,7 @@ export { * @param app Optional app whose `Messaging` service to * return. If not provided, the default `Messaging` service will be returned. * - * @return The default `Messaging` service if no + * @returns The default `Messaging` service if no * app is provided or the `Messaging` service associated with the provided * app. */ diff --git a/src/messaging/messaging-api-request-internal.ts b/src/messaging/messaging-api-request-internal.ts index 31122a3df4..59f67ba3c1 100644 --- a/src/messaging/messaging-api-request-internal.ts +++ b/src/messaging/messaging-api-request-internal.ts @@ -59,10 +59,10 @@ export class FirebaseMessagingRequestHandler { /** * Invokes the request handler with the provided request data. * - * @param {string} host The host to which to send the request. - * @param {string} path The path to which to send the request. - * @param {object} requestData The request data. - * @return {Promise} A promise that resolves with the response. + * @param host The host to which to send the request. + * @param path The path to which to send the request. + * @param requestData The request data. + * @returns A promise that resolves with the response. */ public invokeRequestHandler(host: string, path: string, requestData: object): Promise { const request: HttpRequestConfig = { @@ -100,8 +100,8 @@ export class FirebaseMessagingRequestHandler { * Sends the given array of sub requests as a single batch to FCM, and parses the result into * a BatchResponse object. * - * @param {SubRequest[]} requests An array of sub requests to send. - * @return {Promise} A promise that resolves when the send operation is complete. + * @param requests An array of sub requests to send. + * @returns A promise that resolves when the send operation is complete. */ public sendBatchRequest(requests: SubRequest[]): Promise { return this.batchClient.send(requests) diff --git a/src/messaging/messaging-api.ts b/src/messaging/messaging-api.ts index e586ba039d..cdde578c2b 100644 --- a/src/messaging/messaging-api.ts +++ b/src/messaging/messaging-api.ts @@ -39,13 +39,13 @@ export interface ConditionMessage extends BaseMessage { } /** - * Payload for the admin.messaging.send() operation. The payload contains all the fields + * Payload for the {@link Messaging.send} operation. The payload contains all the fields * in the BaseMessage type, and exactly one of token, topic or condition. */ export type Message = TokenMessage | TopicMessage | ConditionMessage; /** - * Payload for the admin.messaing.sendMulticast() method. The payload contains all the fields + * Payload for the {@link Messaging.sendMulticast} method. The payload contains all the fields * in the BaseMessage type, and a list of tokens. */ export interface MulticastMessage extends BaseMessage { @@ -53,7 +53,7 @@ export interface MulticastMessage extends BaseMessage { } /** - * A notification that can be included in {@link messaging.Message}. + * A notification that can be included in {@link Message}. */ export interface Notification { /** @@ -82,14 +82,14 @@ export interface FcmOptions { /** * Represents the WebPush protocol options that can be included in an - * {@link messaging.Message}. + * {@link Message}. */ export interface WebpushConfig { /** * A collection of WebPush headers. Header values must be strings. * - * See [WebPush specification](https://tools.ietf.org/html/rfc8030#section-5) + * See {@link https://tools.ietf.org/html/rfc8030#section-5 | WebPush specification} * for supported headers. */ headers?: { [key: string]: string }; @@ -124,9 +124,9 @@ export interface WebpushFcmOptions { /** * Represents the WebPush-specific notification options that can be included in - * {@link messaging.WebpushConfig}. This supports most of the standard + * {@link WebpushConfig}. This supports most of the standard * options as defined in the Web Notification - * [specification](https://developer.mozilla.org/en-US/docs/Web/API/notification/Notification). + * {@link https://developer.mozilla.org/en-US/docs/Web/API/notification/Notification | specification}. */ export interface WebpushNotification { @@ -236,9 +236,9 @@ export interface WebpushNotification { /** * Represents the APNs-specific options that can be included in an - * {@link messaging.Message}. Refer to - * [Apple documentation](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingwithAPNs.html) - * for various headers and payload fields supported by APNs. + * {@link Message}. Refer to + * {@link https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingwithAPNs.html | + * Apple documentation} for various headers and payload fields supported by APNs. */ export interface ApnsConfig { /** @@ -271,8 +271,8 @@ export interface ApnsPayload { } /** - * Represents the [aps dictionary](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html) - * that is part of APNs messages. + * Represents the {@link https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html | + * aps dictionary} that is part of APNs messages. */ export interface Aps { @@ -374,7 +374,7 @@ export interface ApnsFcmOptions { /** * Represents the Android-specific options that can be included in an - * {@link messaging.Message}. + * {@link Message}. */ export interface AndroidConfig { @@ -422,7 +422,7 @@ export interface AndroidConfig { /** * Represents the Android-specific notification options that can be included in - * {@link messaging.AndroidConfig}. + * {@link AndroidConfig}. */ export interface AndroidNotification { /** @@ -531,7 +531,8 @@ export interface AndroidNotification { * Sets whether or not this notification is relevant only to the current device. * Some notifications can be bridged to other devices for remote display, such as * a Wear OS watch. This hint can be set to recommend this notification not be bridged. - * See [Wear OS guides](https://developer.android.com/training/wearables/notifications/bridger#existing-method-of-preventing-bridging) + * See {@link https://developer.android.com/training/wearables/notifications/bridger#existing-method-of-preventing-bridging | + * Wear OS guides}. */ localOnly?: boolean; @@ -556,15 +557,16 @@ export interface AndroidNotification { /** * If set to `true`, use the Android framework's default vibrate pattern for the - * notification. Default values are specified in [`config.xml`](https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml). - * If `default_vibrate_timings` is set to `true` and `vibrate_timings` is also set, + * notification. Default values are specified in {@link https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml | + * config.xml}. If `default_vibrate_timings` is set to `true` and `vibrate_timings` is also set, * the default value is used instead of the user-specified `vibrate_timings`. */ defaultVibrateTimings?: boolean; /** * If set to `true`, use the Android framework's default sound for the notification. - * Default values are specified in [`config.xml`](https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml). + * Default values are specified in {@link https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml | + * config.xml}. */ defaultSound?: boolean; @@ -576,7 +578,8 @@ export interface AndroidNotification { /** * If set to `true`, use the Android framework's default LED light settings - * for the notification. Default values are specified in [`config.xml`](https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml). + * for the notification. Default values are specified in {@link https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml | + * config.xml}. * If `default_light_settings` is set to `true` and `light_settings` is also set, * the user-specified `light_settings` is used instead of the default value. */ @@ -590,7 +593,8 @@ export interface AndroidNotification { /** * Sets the number of items this notification represents. May be displayed as a - * badge count for Launchers that support badging. See [`NotificationBadge`(https://developer.android.com/training/notify-user/badges). + * badge count for Launchers that support badging. See {@link https://developer.android.com/training/notify-user/badges | + * NotificationBadge}. * For example, this might be useful if you're using just one notification to * represent multiple new messages but you want the count here to represent * the number of total new messages. If zero or unspecified, systems @@ -602,7 +606,7 @@ export interface AndroidNotification { /** * Represents settings to control notification LED that can be included in - * {@link messaging.AndroidNotification}. + * {@link AndroidNotification}. */ export interface LightSettings { /** @@ -638,10 +642,12 @@ export interface AndroidFcmOptions { * keys and values must both be strings. Keys can be any custom string, * except for the following reserved strings: * - * * `"from"` - * * Anything starting with `"google."`. + *
    + *
  • from
    • + *
  • Anything starting with google.
    • + *
* - * See [Build send requests](/docs/cloud-messaging/send-message) + * See {@link https://firebase.google.com/docs/cloud-messaging/send-message | Build send requests} * for code samples and detailed documentation. */ export interface DataMessagePayload { @@ -653,7 +659,7 @@ export interface DataMessagePayload { * Notification messages let developers send up to 4KB of predefined * key-value pairs. Accepted keys are outlined below. * - * See [Build send requests](/docs/cloud-messaging/send-message) + * See {@link https://firebase.google.com/docs/cloud-messaging/send-message | Build send requests} * for code samples and detailed documentation. */ export interface NotificationMessagePayload { @@ -730,13 +736,14 @@ export interface NotificationMessagePayload { * the body text to the user's current localization. * * **iOS:** Corresponds to `loc-key` in the APNs payload. See - * [Payload Key Reference](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html) - * and - * [Localizing the Content of Your Remote Notifications](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CreatingtheNotificationPayload.html#//apple_ref/doc/uid/TP40008194-CH10-SW9) - * for more information. + * {@link https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html | + * Payload Key Reference} and + * {@link https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CreatingtheNotificationPayload.html#//apple_ref/doc/uid/TP40008194-CH10-SW9 | + * Localizing the Content of Your Remote Notifications} for more information. * * **Android:** See - * [String Resources](http://developer.android.com/guide/topics/resources/string-resource.html) * for more information. + * {@link http://developer.android.com/guide/topics/resources/string-resource.html | String Resources} + * for more information. * * **Platforms:** iOS, Android */ @@ -750,14 +757,14 @@ export interface NotificationMessagePayload { * The value should be a stringified JSON array. * * **iOS:** Corresponds to `loc-args` in the APNs payload. See - * [Payload Key Reference](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html) - * and - * [Localizing the Content of Your Remote Notifications](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CreatingtheNotificationPayload.html#//apple_ref/doc/uid/TP40008194-CH10-SW9) - * for more information. + * {@link https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html | + * Payload Key Reference} and + * {@link https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CreatingtheNotificationPayload.html#//apple_ref/doc/uid/TP40008194-CH10-SW9 | + * Localizing the Content of Your Remote Notifications} for more information. * * **Android:** See - * [Formatting and Styling](http://developer.android.com/guide/topics/resources/string-resource.html#FormattingAndStyling) - * for more information. + * {@link http://developer.android.com/guide/topics/resources/string-resource.html#FormattingAndStyling | + * Formatting and Styling} for more information. * * **Platforms:** iOS, Android */ @@ -777,13 +784,13 @@ export interface NotificationMessagePayload { * the title text to the user's current localization. * * **iOS:** Corresponds to `title-loc-key` in the APNs payload. See - * [Payload Key Reference](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html) - * and - * [Localizing the Content of Your Remote Notifications](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CreatingtheNotificationPayload.html#//apple_ref/doc/uid/TP40008194-CH10-SW9) - * for more information. + * {@link https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html | + * Payload Key Reference} and + * {@link https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CreatingtheNotificationPayload.html#//apple_ref/doc/uid/TP40008194-CH10-SW9 | + * Localizing the Content of Your Remote Notifications} for more information. * * **Android:** See - * [String Resources](http://developer.android.com/guide/topics/resources/string-resource.html) + * {@link http://developer.android.com/guide/topics/resources/string-resource.html | String Resources} * for more information. * * **Platforms:** iOS, Android @@ -798,14 +805,14 @@ export interface NotificationMessagePayload { * The value should be a stringified JSON array. * * **iOS:** Corresponds to `title-loc-args` in the APNs payload. See - * [Payload Key Reference](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html) - * and - * [Localizing the Content of Your Remote Notifications](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CreatingtheNotificationPayload.html#//apple_ref/doc/uid/TP40008194-CH10-SW9) - * for more information. + * {@link https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html | + * Payload Key Reference} and + * {@link https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CreatingtheNotificationPayload.html#//apple_ref/doc/uid/TP40008194-CH10-SW9 | + * Localizing the Content of Your Remote Notifications} for more information. * * **Android:** See - * [Formatting and Styling](http://developer.android.com/guide/topics/resources/string-resource.html#FormattingAndStyling) - * for more information. + * {@link http://developer.android.com/guide/topics/resources/string-resource.html#FormattingAndStyling | + * Formatting and Styling} for more information. * * **Platforms:** iOS, Android */ @@ -817,8 +824,7 @@ export interface NotificationMessagePayload { * Interface representing a Firebase Cloud Messaging message payload. One or * both of the `data` and `notification` keys are required. * - * See - * [Build send requests](/docs/cloud-messaging/send-message) + * See {@link https://firebase.google.com/docs/cloud-messaging/send-message | Build send requests} * for code samples and detailed documentation. */ export interface MessagingPayload { @@ -838,7 +844,7 @@ export interface MessagingPayload { * Interface representing the options that can be provided when sending a * message via the FCM legacy APIs. * - * See [Build send requests](/docs/cloud-messaging/send-message) + * See {@link https://firebase.google.com/docs/cloud-messaging/send-message | Build send requests} * for code samples and detailed documentation. */ export interface MessagingOptions { @@ -866,7 +872,8 @@ export interface MessagingOptions { * app can wake a sleeping device and open a network connection to your server. * * For more information, see - * [Setting the priority of a message](/docs/cloud-messaging/concept-options#setting-the-priority-of-a-message). + * {@link https://firebase.google.com/docs/cloud-messaging/concept-options#setting-the-priority-of-a-message | + * Setting the priority of a message}. * * **Default value:** `"high"` for notification messages, `"normal"` for data * messages @@ -877,7 +884,7 @@ export interface MessagingOptions { * How long (in seconds) the message should be kept in FCM storage if the device * is offline. The maximum time to live supported is four weeks, and the default * value is also four weeks. For more information, see - * [Setting the lifespan of a message](/docs/cloud-messaging/concept-options#ttl). + * {@link https://firebase.google.com/docs/cloud-messaging/concept-options#ttl | Setting the lifespan of a message}. * * **Default value:** `2419200` (representing four weeks, in seconds) */ @@ -904,7 +911,8 @@ export interface MessagingOptions { * On iOS, use this field to represent `mutable-content` in the APNs payload. * When a notification is sent and this is set to `true`, the content of the * notification can be modified before it is displayed, using a - * [Notification Service app extension](https://developer.apple.com/reference/usernotifications/unnotificationserviceextension) + * {@link https://developer.apple.com/reference/usernotifications/unnotificationserviceextension | + * Notification Service app extension}. * * On Android and Web, this parameter will be ignored. * @@ -957,8 +965,8 @@ export interface MessagingDeviceResult { * via the FCM legacy APIs. * * See - * [Send to individual devices](/docs/cloud-messaging/admin/send-messages#send_to_individual_devices) - * for code samples and detailed documentation. + * {@link https://firebase.google.com/docs/cloud-messaging/admin/send-messages#send_to_individual_devices | + * Send to individual devices} for code samples and detailed documentation. */ export interface MessagingDevicesResponse { canonicalRegistrationTokenCount: number; @@ -969,13 +977,12 @@ export interface MessagingDevicesResponse { } /** - * Interface representing the server response from the - * {@link messaging.Messaging.sendToDeviceGroup `sendToDeviceGroup()`} + * Interface representing the server response from the {@link Messaging.sendToDeviceGroup} * method. * * See - * [Send messages to device groups](/docs/cloud-messaging/send-message?authuser=0#send_messages_to_device_groups) - * for code samples and detailed documentation. + * {@link https://firebase.google.com/docs/cloud-messaging/send-message?authuser=0#send_messages_to_device_groups | + * Send messages to device groups} for code samples and detailed documentation. */ export interface MessagingDeviceGroupResponse { @@ -996,12 +1003,11 @@ export interface MessagingDeviceGroupResponse { } /** - * Interface representing the server response from the legacy - * {@link messaging.Messaging.sendToTopic `sendToTopic()`} method. + * Interface representing the server response from the legacy {@link Messaging.sendToTopic} method. * * See - * [Send to a topic](/docs/cloud-messaging/admin/send-messages#send_to_a_topic) - * for code samples and detailed documentation. + * {@link https://firebase.google.com/docs/cloud-messaging/admin/send-messages#send_to_a_topic | + * Send to a topic} for code samples and detailed documentation. */ export interface MessagingTopicResponse { /** @@ -1013,11 +1019,11 @@ export interface MessagingTopicResponse { /** * Interface representing the server response from the legacy - * {@link messaging.Messaging.sendToCondition `sendToCondition()`} method. + * {@link Messaging.sendToCondition} method. * * See - * [Send to a condition](/docs/cloud-messaging/admin/send-messages#send_to_a_condition) - * for code samples and detailed documentation. + * {@link https://firebase.google.com/docs/cloud-messaging/admin/send-messages#send_to_a_condition | + * Send to a condition} for code samples and detailed documentation. */ export interface MessagingConditionResponse { /** @@ -1029,13 +1035,12 @@ export interface MessagingConditionResponse { /** * Interface representing the server response from the - * {@link messaging.Messaging.subscribeToTopic `subscribeToTopic()`} and - * {@link messaging.Messaging.unsubscribeFromTopic `unsubscribeFromTopic()`} + * {@link Messaging.subscribeToTopic} and {@link Messaging.unsubscribeFromTopic} * methods. * * See - * [Manage topics from the server](/docs/cloud-messaging/manage-topics) - * for code samples and detailed documentation. + * {@link https://firebase.google.com/docs/cloud-messaging/manage-topics | + * Manage topics from the server} for code samples and detailed documentation. */ export interface MessagingTopicManagementResponse { /** @@ -1052,15 +1057,14 @@ export interface MessagingTopicManagementResponse { /** * An array of errors corresponding to the provided registration token(s). The - * length of this array will be equal to [`failureCount`](#failureCount). + * length of this array will be equal to {@link MessagingTopicManagementResponse.failureCount}. */ errors: FirebaseArrayIndexError[]; } /** * Interface representing the server response from the - * {@link messaging.Messaging.sendAll `sendAll()`} and - * {@link messaging.Messaging.sendMulticast `sendMulticast()`} methods. + * {@link Messaging.sendAll} and {@link Messaging.sendMulticast} methods. */ export interface BatchResponse { diff --git a/src/messaging/messaging-errors-internal.ts b/src/messaging/messaging-errors-internal.ts index ecd3155bae..e87f635d55 100644 --- a/src/messaging/messaging-errors-internal.ts +++ b/src/messaging/messaging-errors-internal.ts @@ -22,8 +22,8 @@ import * as validator from '../utils/validator'; * Creates a new FirebaseMessagingError by extracting the error code, message and other relevant * details from an HTTP error response. * - * @param {HttpError} err The HttpError to convert into a Firebase error - * @return {FirebaseMessagingError} A Firebase error that can be returned to the user. + * @param err The HttpError to convert into a Firebase error + * @returns A Firebase error that can be returned to the user. */ export function createFirebaseError(err: HttpError): FirebaseMessagingError { if (err.response.isJson()) { @@ -62,8 +62,8 @@ export function createFirebaseError(err: HttpError): FirebaseMessagingError { } /** - * @param {object} response The response to check for errors. - * @return {string|null} The error code if present; null otherwise. + * @param response The response to check for errors. + * @returns The error code if present; null otherwise. */ export function getErrorCode(response: any): string | null { if (validator.isNonNullObject(response) && 'error' in response) { @@ -92,8 +92,8 @@ export function getErrorCode(response: any): string | null { /** * Extracts error message from the given response object. * - * @param {object} response The response to check for errors. - * @return {string|null} The error message if present; null otherwise. + * @param response The response to check for errors. + * @returns The error message if present; null otherwise. */ function getErrorMessage(response: any): string | null { if (validator.isNonNullObject(response) && diff --git a/src/messaging/messaging-internal.ts b/src/messaging/messaging-internal.ts index 4d68965774..3e832a2a8c 100644 --- a/src/messaging/messaging-internal.ts +++ b/src/messaging/messaging-internal.ts @@ -372,7 +372,7 @@ function validateApsAlert(alert: string | ApsAlert | undefined): void { * and notification fields. If successful, transforms the input object by renaming keys to valid * Android keys. Also transforms the ttl value to the format expected by FCM service. * - * @param {AndroidConfig} config An object to be validated. + * @param config An object to be validated. */ function validateAndroidConfig(config: AndroidConfig | undefined): void { if (typeof config === 'undefined') { @@ -585,8 +585,8 @@ function validateAndroidFcmOptions(fcmOptions: AndroidFcmOptions | undefined): v * Returns the duration in seconds with up to nine fractional * digits, terminated by 's'. Example: "3.5s". * - * @param {number} milliseconds The duration in milliseconds. - * @return {string} The resulting formatted string in seconds with up to nine fractional + * @param milliseconds The duration in milliseconds. + * @returns The resulting formatted string in seconds with up to nine fractional * digits, terminated by 's'. */ function transformMillisecondsToSecondsString(milliseconds: number): string { diff --git a/src/messaging/messaging-namespace.ts b/src/messaging/messaging-namespace.ts index b49fdb564a..2e34b87760 100644 --- a/src/messaging/messaging-namespace.ts +++ b/src/messaging/messaging-namespace.ts @@ -54,14 +54,12 @@ import { } from './messaging-api'; /** - * Gets the {@link messaging.Messaging `Messaging`} service for the + * Gets the {@link firebase-admin.messaging#Messaging} service for the * default app or a given app. * * `admin.messaging()` can be called with no arguments to access the default - * app's {@link messaging.Messaging `Messaging`} service or as - * `admin.messaging(app)` to access the - * {@link messaging.Messaging `Messaging`} service associated with a - * specific app. + * app's `Messaging` service or as `admin.messaging(app)` to access the + * `Messaging` service associated with a specific app. * * @example * ```javascript @@ -78,7 +76,7 @@ import { * @param app Optional app whose `Messaging` service to * return. If not provided, the default `Messaging` service will be returned. * - * @return The default `Messaging` service if no + * @returns The default `Messaging` service if no * app is provided or the `Messaging` service associated with the provided * app. */ diff --git a/src/messaging/messaging.ts b/src/messaging/messaging.ts index b1803a513e..688ec08fdb 100644 --- a/src/messaging/messaging.ts +++ b/src/messaging/messaging.ts @@ -107,9 +107,9 @@ const MESSAGING_CONDITION_RESPONSE_KEYS_MAP = { /** * Maps a raw FCM server response to a MessagingDevicesResponse object. * - * @param {object} response The raw FCM server response to map. + * @param response The raw FCM server response to map. * - * @return {MessagingDeviceGroupResponse} The mapped MessagingDevicesResponse object. + * @returns The mapped MessagingDevicesResponse object. */ function mapRawResponseToDevicesResponse(response: object): MessagingDevicesResponse { // Rename properties on the server response @@ -134,9 +134,9 @@ function mapRawResponseToDevicesResponse(response: object): MessagingDevicesResp /** * Maps a raw FCM server response to a MessagingDeviceGroupResponse object. * - * @param {object} response The raw FCM server response to map. + * @param response The raw FCM server response to map. * - * @return {MessagingDeviceGroupResponse} The mapped MessagingDeviceGroupResponse object. + * @returns The mapped MessagingDeviceGroupResponse object. */ function mapRawResponseToDeviceGroupResponse(response: object): MessagingDeviceGroupResponse { // Rename properties on the server response @@ -154,7 +154,7 @@ function mapRawResponseToDeviceGroupResponse(response: object): MessagingDeviceG * * @param {object} response The raw FCM server response to map. * - * @return {MessagingTopicManagementResponse} The mapped MessagingTopicManagementResponse object. + * @returns {MessagingTopicManagementResponse} The mapped MessagingTopicManagementResponse object. */ function mapRawResponseToTopicManagementResponse(response: object): MessagingTopicManagementResponse { // Add the success and failure counts. @@ -196,17 +196,7 @@ export class Messaging { private readonly messagingRequestHandler: FirebaseMessagingRequestHandler; /** - * Gets the {@link messaging.Messaging `Messaging`} service for the - * current app. - * - * @example - * ```javascript - * var messaging = app.messaging(); - * // The above is shorthand for: - * // var messaging = admin.messaging(app); - * ``` - * - * @return The `Messaging` service for the current app. + * @internal */ constructor(app: App) { if (!validator.isNonNullObject(app) || !('options' in app)) { @@ -221,7 +211,7 @@ export class Messaging { } /** - * The {@link app.App app} associated with the current `Messaging` service + * The {@link firebase-admin.app#App} associated with the current `Messaging` service * instance. * * @example @@ -239,7 +229,7 @@ export class Messaging { * @param message The message payload. * @param dryRun Whether to send the message in the dry-run * (validation only) mode. - * @return A promise fulfilled with a unique message ID + * @returns A promise fulfilled with a unique message ID * string after the message has been successfully handed off to the FCM * service for delivery. */ @@ -279,7 +269,7 @@ export class Messaging { * containing up to 500 messages. * @param dryRun Whether to send the messages in the dry-run * (validation only) mode. - * @return A Promise fulfilled with an object representing the result of the + * @returns A Promise fulfilled with an object representing the result of the * send operation. */ public sendAll(messages: Message[], dryRun?: boolean): Promise { @@ -337,7 +327,7 @@ export class Messaging { * containing up to 500 tokens. * @param dryRun Whether to send the message in the dry-run * (validation only) mode. - * @return A Promise fulfilled with an object representing the result of the + * @returns A Promise fulfilled with an object representing the result of the * send operation. */ public sendMulticast(message: MulticastMessage, dryRun?: boolean): Promise { @@ -374,8 +364,8 @@ export class Messaging { * Sends an FCM message to a single device corresponding to the provided * registration token. * - * See - * [Send to individual devices](/docs/cloud-messaging/admin/legacy-fcm#send_to_individual_devices) + * See {@link https://firebase.google.com/docs/cloud-messaging/admin/legacy-fcm#send_to_individual_devices | + * Send to individual devices} * for code samples and detailed documentation. Takes either a * `registrationToken` to send to a single device or a * `registrationTokens` parameter containing an array of tokens to send @@ -387,7 +377,7 @@ export class Messaging { * @param options Optional options to * alter the message. * - * @return A promise fulfilled with the server's response after the message + * @returns A promise fulfilled with the server's response after the message * has been sent. */ public sendToDevice( @@ -447,9 +437,8 @@ export class Messaging { * Sends an FCM message to a device group corresponding to the provided * notification key. * - * See - * [Send to a device group](/docs/cloud-messaging/admin/legacy-fcm#send_to_a_device_group) - * for code samples and detailed documentation. + * See {@link https://firebase.google.com/docs/cloud-messaging/admin/legacy-fcm#send_to_a_device_group | + * Send to a device group} for code samples and detailed documentation. * * @param notificationKey The notification key for the device group to * which to send the message. @@ -457,7 +446,7 @@ export class Messaging { * @param options Optional options to * alter the message. * - * @return A promise fulfilled with the server's response after the message + * @returns A promise fulfilled with the server's response after the message * has been sent. */ public sendToDeviceGroup( @@ -531,16 +520,15 @@ export class Messaging { /** * Sends an FCM message to a topic. * - * See - * [Send to a topic](/docs/cloud-messaging/admin/legacy-fcm#send_to_a_topic) - * for code samples and detailed documentation. + * See {@link https://firebase.google.com/docs/cloud-messaging/admin/legacy-fcm#send_to_a_topic | + * Send to a topic} for code samples and detailed documentation. * * @param topic The topic to which to send the message. * @param payload The message payload. * @param options Optional options to * alter the message. * - * @return A promise fulfilled with the server's response after the message + * @returns A promise fulfilled with the server's response after the message * has been sent. */ public sendToTopic( @@ -581,8 +569,8 @@ export class Messaging { /** * Sends an FCM message to a condition. * - * See - * [Send to a condition](/docs/cloud-messaging/admin/legacy-fcm#send_to_a_condition) + * See {@link https://firebase.google.com/docs/cloud-messaging/admin/legacy-fcm#send_to_a_condition | + * Send to a condition} * for code samples and detailed documentation. * * @param condition The condition determining to which topics to send @@ -591,7 +579,7 @@ export class Messaging { * @param options Optional options to * alter the message. * - * @return A promise fulfilled with the server's response after the message + * @returns A promise fulfilled with the server's response after the message * has been sent. */ public sendToCondition( @@ -639,8 +627,8 @@ export class Messaging { /** * Subscribes a device to an FCM topic. * - * See [Subscribe to a - * topic](/docs/cloud-messaging/manage-topics#suscribe_and_unsubscribe_using_the) + * See {@link https://firebase.google.com/docs/cloud-messaging/manage-topics#suscribe_and_unsubscribe_using_the | + * Subscribe to a topic} * for code samples and detailed documentation. Optionally, you can provide an * array of tokens to subscribe multiple devices. * @@ -648,7 +636,7 @@ export class Messaging { * for the devices to subscribe to the topic. * @param topic The topic to which to subscribe. * - * @return A promise fulfilled with the server's response after the device has been + * @returns A promise fulfilled with the server's response after the device has been * subscribed to the topic. */ public subscribeToTopic( @@ -666,8 +654,8 @@ export class Messaging { /** * Unsubscribes a device from an FCM topic. * - * See [Unsubscribe from a - * topic](/docs/cloud-messaging/admin/manage-topic-subscriptions#unsubscribe_from_a_topic) + * See {@link https://firebase.google.com/docs/cloud-messaging/admin/manage-topic-subscriptions#unsubscribe_from_a_topic | + * Unsubscribe from a topic} * for code samples and detailed documentation. Optionally, you can provide an * array of tokens to unsubscribe multiple devices. * @@ -675,7 +663,7 @@ export class Messaging { * device registration tokens to unsubscribe from the topic. * @param topic The topic from which to unsubscribe. * - * @return A promise fulfilled with the server's response after the device has been + * @returns A promise fulfilled with the server's response after the device has been * unsubscribed from the topic. */ public unsubscribeFromTopic( @@ -715,13 +703,13 @@ export class Messaging { /** * Helper method which sends and handles topic subscription management requests. * - * @param {string|string[]} registrationTokenOrTokens The registration token or an array of + * @param registrationTokenOrTokens The registration token or an array of * registration tokens to unsubscribe from the topic. - * @param {string} topic The topic to which to subscribe. - * @param {string} methodName The name of the original method called. - * @param {string} path The endpoint path to use for the request. + * @param topic The topic to which to subscribe. + * @param methodName The name of the original method called. + * @param path The endpoint path to use for the request. * - * @return {Promise} A Promise fulfilled with the parsed server + * @returns A Promise fulfilled with the parsed server * response. */ private sendTopicManagementRequest( @@ -766,8 +754,8 @@ export class Messaging { /** * Validates the types of the messaging payload and options. If invalid, an error will be thrown. * - * @param {MessagingPayload} payload The messaging payload to validate. - * @param {MessagingOptions} options The messaging options to validate. + * @param payload The messaging payload to validate. + * @param options The messaging options to validate. */ private validateMessagingPayloadAndOptionsTypes( payload: MessagingPayload, @@ -793,9 +781,9 @@ export class Messaging { /** * Validates the messaging payload. If invalid, an error will be thrown. * - * @param {MessagingPayload} payload The messaging payload to validate. + * @param payload The messaging payload to validate. * - * @return {MessagingPayload} A copy of the provided payload with whitelisted properties switched + * @returns A copy of the provided payload with whitelisted properties switched * from camelCase to underscore_case. */ private validateMessagingPayload(payload: MessagingPayload): MessagingPayload { @@ -884,9 +872,9 @@ export class Messaging { /** * Validates the messaging options. If invalid, an error will be thrown. * - * @param {MessagingOptions} options The messaging options to validate. + * @param options The messaging options to validate. * - * @return {MessagingOptions} A copy of the provided options with whitelisted properties switched + * @returns A copy of the provided options with whitelisted properties switched * from camelCase to underscore_case. */ private validateMessagingOptions(options: MessagingOptions): MessagingOptions { @@ -963,9 +951,9 @@ export class Messaging { /** * Validates the type of the provided registration token(s). If invalid, an error will be thrown. * - * @param {string|string[]} registrationTokenOrTokens The registration token(s) to validate. - * @param {string} method The method name to use in error messages. - * @param {ErrorInfo?} [errorInfo] The error info to use if the registration tokens are invalid. + * @param registrationTokenOrTokens The registration token(s) to validate. + * @param method The method name to use in error messages. + * @param errorInfo The error info to use if the registration tokens are invalid. */ private validateRegistrationTokensType( registrationTokenOrTokens: string | string[], @@ -985,10 +973,10 @@ export class Messaging { /** * Validates the provided registration tokens. If invalid, an error will be thrown. * - * @param {string|string[]} registrationTokenOrTokens The registration token or an array of + * @param registrationTokenOrTokens The registration token or an array of * registration tokens to validate. - * @param {string} method The method name to use in error messages. - * @param {errorInfo?} [ErrorInfo] The error info to use if the registration tokens are invalid. + * @param method The method name to use in error messages. + * @param errorInfo The error info to use if the registration tokens are invalid. */ private validateRegistrationTokens( registrationTokenOrTokens: string | string[], @@ -1021,9 +1009,9 @@ export class Messaging { /** * Validates the type of the provided topic. If invalid, an error will be thrown. * - * @param {string} topic The topic to validate. - * @param {string} method The method name to use in error messages. - * @param {ErrorInfo?} [errorInfo] The error info to use if the topic is invalid. + * @param topic The topic to validate. + * @param method The method name to use in error messages. + * @param errorInfo The error info to use if the topic is invalid. */ private validateTopicType( topic: string | string[], @@ -1042,9 +1030,9 @@ export class Messaging { /** * Validates the provided topic. If invalid, an error will be thrown. * - * @param {string} topic The topic to validate. - * @param {string} method The method name to use in error messages. - * @param {ErrorInfo?} [errorInfo] The error info to use if the topic is invalid. + * @param topic The topic to validate. + * @param method The method name to use in error messages. + * @param errorInfo The error info to use if the topic is invalid. */ private validateTopic( topic: string, @@ -1063,9 +1051,9 @@ export class Messaging { /** * Normalizes the provided topic name by prepending it with '/topics/', if necessary. * - * @param {string} topic The topic name to normalize. + * @param topic The topic name to normalize. * - * @return {string} The normalized topic name. + * @returns The normalized topic name. */ private normalizeTopic(topic: string): string { if (!/^\/topics\//.test(topic)) { diff --git a/src/project-management/android-app.ts b/src/project-management/android-app.ts index 5756051c28..dc63b47da9 100644 --- a/src/project-management/android-app.ts +++ b/src/project-management/android-app.ts @@ -42,8 +42,7 @@ export interface AndroidAppMetadata extends AppMetadata { /** * A reference to a Firebase Android app. * - * Do not call this constructor directly. Instead, use - * [`projectManagement.androidApp()`](projectManagement.ProjectManagement#androidApp). + * Do not call this constructor directly. Instead, use {@link ProjectManagement.androidApp}. */ export class AndroidApp { @@ -66,7 +65,7 @@ export class AndroidApp { /** * Retrieves metadata about this Android app. * - * @return A promise that resolves to the retrieved metadata about this Android app. + * @returns A promise that resolves to the retrieved metadata about this Android app. */ public getMetadata(): Promise { return this.requestHandler.getResource(this.resourceName) @@ -101,7 +100,7 @@ export class AndroidApp { * * @param newDisplayName The new display name to set. * - * @return A promise that resolves when the display name has been set. + * @returns A promise that resolves when the display name has been set. */ public setDisplayName(newDisplayName: string): Promise { return this.requestHandler.setDisplayName(this.resourceName, newDisplayName); @@ -110,7 +109,7 @@ export class AndroidApp { /** * Gets the list of SHA certificates associated with this Android app in Firebase. * - * @return The list of SHA-1 and SHA-256 certificates associated with this Android app in + * @returns The list of SHA-1 and SHA-256 certificates associated with this Android app in * Firebase. */ public getShaCertificates(): Promise { @@ -151,7 +150,7 @@ export class AndroidApp { * * @param certificateToAdd The SHA certificate to add. * - * @return A promise that resolves when the given certificate + * @returns A promise that resolves when the given certificate * has been added to the Android app. */ public addShaCertificate(certificateToAdd: ShaCertificate): Promise { @@ -163,7 +162,7 @@ export class AndroidApp { * * @param certificateToDelete The SHA certificate to delete. * - * @return A promise that resolves when the specified + * @returns A promise that resolves when the specified * certificate has been removed from the Android app. */ public deleteShaCertificate(certificateToDelete: ShaCertificate): Promise { @@ -179,7 +178,7 @@ export class AndroidApp { /** * Gets the configuration artifact associated with this app. * - * @return A promise that resolves to the Android app's + * @returns A promise that resolves to the Android app's * Firebase config file, in UTF-8 string format. This string is typically * intended to be written to a JSON file that gets shipped with your Android * app. diff --git a/src/project-management/index.ts b/src/project-management/index.ts index 97ff5c203c..92dd34f449 100644 --- a/src/project-management/index.ts +++ b/src/project-management/index.ts @@ -24,14 +24,11 @@ export { AndroidApp, AndroidAppMetadata, ShaCertificate } from './android-app'; export { IosApp, IosAppMetadata } from './ios-app'; /** - * Gets the {@link projectManagement.ProjectManagement - * `ProjectManagement`} service for the default app or a given app. + * Gets the {@link ProjectManagement} service for the default app or a given app. * * `getProjectManagement()` can be called with no arguments to access the - * default app's {@link projectManagement.ProjectManagement - * `ProjectManagement`} service, or as `getProjectManagement(app)` to access - * the {@link projectManagement.ProjectManagement `ProjectManagement`} - * service associated with a specific app. + * default app's `ProjectManagement` service, or as `getProjectManagement(app)` to access + * the `ProjectManagement` service associated with a specific app. * * @example * ```javascript @@ -48,7 +45,7 @@ export { IosApp, IosAppMetadata } from './ios-app'; * @param app Optional app whose `ProjectManagement` service * to return. If not provided, the default `ProjectManagement` service will * be returned. * - * @return The default `ProjectManagement` service if no app is provided or the + * @returns The default `ProjectManagement` service if no app is provided or the * `ProjectManagement` service associated with the provided app. */ export function getProjectManagement(app?: App): ProjectManagement { diff --git a/src/project-management/ios-app.ts b/src/project-management/ios-app.ts index 0becebbb02..dc1ff3a23c 100644 --- a/src/project-management/ios-app.ts +++ b/src/project-management/ios-app.ts @@ -39,8 +39,7 @@ export interface IosAppMetadata extends AppMetadata { /** * A reference to a Firebase iOS app. * - * Do not call this constructor directly. Instead, use - * [`projectManagement.iosApp()`](projectManagement.ProjectManagement#iosApp). + * Do not call this constructor directly. Instead, use {@link ProjectManagement.iosApp}. */ export class IosApp { @@ -63,7 +62,7 @@ export class IosApp { /** * Retrieves metadata about this iOS app. * - * @return A promise that + * @returns A promise that * resolves to the retrieved metadata about this iOS app. */ public getMetadata(): Promise { @@ -99,7 +98,7 @@ export class IosApp { * * @param newDisplayName The new display name to set. * - * @return A promise that resolves when the display name has + * @returns A promise that resolves when the display name has * been set. */ public setDisplayName(newDisplayName: string): Promise { @@ -109,7 +108,7 @@ export class IosApp { /** * Gets the configuration artifact associated with this app. * - * @return A promise that resolves to the iOS app's Firebase + * @returns A promise that resolves to the iOS app's Firebase * config file, in UTF-8 string format. This string is typically intended to * be written to a plist file that gets shipped with your iOS app. */ diff --git a/src/project-management/project-management-api-request-internal.ts b/src/project-management/project-management-api-request-internal.ts index 4f5b876435..7c9651e50a 100644 --- a/src/project-management/project-management-api-request-internal.ts +++ b/src/project-management/project-management-api-request-internal.ts @@ -58,7 +58,7 @@ export function assertServerResponse( * Class that provides mechanism to send requests to the Firebase project management backend * endpoints. * - * @private + * @internal */ export class ProjectManagementRequestHandler { private readonly baseUrl: string = @@ -122,7 +122,7 @@ export class ProjectManagementRequestHandler { } /** - * @param {string} parentResourceName Fully-qualified resource name of the project whose Android + * @param parentResourceName Fully-qualified resource name of the project whose Android * apps you want to list. */ public listAndroidApps(parentResourceName: string): Promise { @@ -134,7 +134,7 @@ export class ProjectManagementRequestHandler { } /** - * @param {string} parentResourceName Fully-qualified resource name of the project whose iOS apps + * @param parentResourceName Fully-qualified resource name of the project whose iOS apps * you want to list. */ public listIosApps(parentResourceName: string): Promise { @@ -146,7 +146,7 @@ export class ProjectManagementRequestHandler { } /** - * @param {string} parentResourceName Fully-qualified resource name of the project whose iOS apps + * @param parentResourceName Fully-qualified resource name of the project whose iOS apps * you want to list. */ public listAppMetadata(parentResourceName: string): Promise { @@ -158,7 +158,7 @@ export class ProjectManagementRequestHandler { } /** - * @param {string} parentResourceName Fully-qualified resource name of the project that you want + * @param parentResourceName Fully-qualified resource name of the project that you want * to create the Android app within. */ public createAndroidApp( @@ -185,7 +185,7 @@ export class ProjectManagementRequestHandler { } /** - * @param {string} parentResourceName Fully-qualified resource name of the project that you want + * @param parentResourceName Fully-qualified resource name of the project that you want * to create the iOS app within. */ public createIosApp( @@ -212,7 +212,7 @@ export class ProjectManagementRequestHandler { } /** - * @param {string} resourceName Fully-qualified resource name of the entity whose display name you + * @param resourceName Fully-qualified resource name of the entity whose display name you * want to set. */ public setDisplayName(resourceName: string, newDisplayName: string): Promise { @@ -226,7 +226,7 @@ export class ProjectManagementRequestHandler { } /** - * @param {string} parentResourceName Fully-qualified resource name of the Android app whose SHA + * @param parentResourceName Fully-qualified resource name of the Android app whose SHA * certificates you want to get. */ public getAndroidShaCertificates(parentResourceName: string): Promise { @@ -235,7 +235,7 @@ export class ProjectManagementRequestHandler { } /** - * @param {string} parentResourceName Fully-qualified resource name of the Android app that you + * @param parentResourceName Fully-qualified resource name of the Android app that you * want to add the given SHA certificate to. */ public addAndroidShaCertificate( @@ -250,7 +250,7 @@ export class ProjectManagementRequestHandler { } /** - * @param {string} parentResourceName Fully-qualified resource name of the app whose config you + * @param parentResourceName Fully-qualified resource name of the app whose config you * want to get. */ public getConfig(parentResourceName: string): Promise { @@ -259,7 +259,7 @@ export class ProjectManagementRequestHandler { } /** - * @param {string} parentResourceName Fully-qualified resource name of the entity that you want to + * @param parentResourceName Fully-qualified resource name of the entity that you want to * get. */ public getResource(parentResourceName: string): Promise { @@ -267,7 +267,7 @@ export class ProjectManagementRequestHandler { } /** - * @param {string} resourceName Fully-qualified resource name of the entity that you want to + * @param resourceName Fully-qualified resource name of the entity that you want to * delete. */ public deleteResource(resourceName: string): Promise { diff --git a/src/project-management/project-management-namespace.ts b/src/project-management/project-management-namespace.ts index e37903cda8..ae9e4cf0b3 100644 --- a/src/project-management/project-management-namespace.ts +++ b/src/project-management/project-management-namespace.ts @@ -31,14 +31,12 @@ import { } from './ios-app'; /** - * Gets the {@link projectManagement.ProjectManagement - * `ProjectManagement`} service for the default app or a given app. + * Gets the {@link firebase-admin.project-management#ProjectManagement} service for the + * default app or a given app. * * `admin.projectManagement()` can be called with no arguments to access the - * default app's {@link projectManagement.ProjectManagement - * `ProjectManagement`} service, or as `admin.projectManagement(app)` to access - * the {@link projectManagement.ProjectManagement `ProjectManagement`} - * service associated with a specific app. + * default app's `ProjectManagement` service, or as `admin.projectManagement(app)` to access + * the `ProjectManagement` service associated with a specific app. * * @example * ```javascript @@ -55,7 +53,7 @@ import { * @param app Optional app whose `ProjectManagement` service * to return. If not provided, the default `ProjectManagement` service will * be returned. * - * @return The default `ProjectManagement` service if no app is provided or the + * @returns The default `ProjectManagement` service if no app is provided or the * `ProjectManagement` service associated with the provided app. */ export declare function projectManagement(app?: App): projectManagement.ProjectManagement; diff --git a/src/project-management/project-management.ts b/src/project-management/project-management.ts index 5b0d691823..ff7a5089bb 100644 --- a/src/project-management/project-management.ts +++ b/src/project-management/project-management.ts @@ -25,9 +25,6 @@ import { AppMetadata, AppPlatform } from './app-metadata'; /** * The Firebase ProjectManagement service interface. - * - * Do not call this constructor directly. Instead, use - * [`admin.projectManagement()`](projectManagement#projectManagement). */ export class ProjectManagement { @@ -53,7 +50,7 @@ export class ProjectManagement { /** * Lists up to 100 Firebase Android apps associated with this Firebase project. * - * @return The list of Android apps. + * @returns The list of Android apps. */ public listAndroidApps(): Promise { return this.listPlatformApps('android', 'listAndroidApps()'); @@ -62,7 +59,7 @@ export class ProjectManagement { /** * Lists up to 100 Firebase iOS apps associated with this Firebase project. * - * @return The list of iOS apps. + * @returns The list of iOS apps. */ public listIosApps(): Promise { return this.listPlatformApps('ios', 'listIosApps()'); @@ -76,7 +73,7 @@ export class ProjectManagement { * * @param appId The `appId` of the Android app to reference. * - * @return An `AndroidApp` object that references the specified Firebase Android app. + * @returns An `AndroidApp` object that references the specified Firebase Android app. */ public androidApp(appId: string): AndroidApp { return new AndroidApp(appId, this.requestHandler); @@ -90,7 +87,7 @@ export class ProjectManagement { * * @param appId The `appId` of the iOS app to reference. * - * @return An `iOSApp` object that references the specified Firebase iOS app. + * @returns An `iOSApp` object that references the specified Firebase iOS app. */ public iosApp(appId: string): IosApp { return new IosApp(appId, this.requestHandler); @@ -103,7 +100,7 @@ export class ProjectManagement { * * @param shaHash The SHA-1 or SHA-256 hash for this certificate. * - * @return A `ShaCertificate` object contains the specified SHA hash. + * @returns A `ShaCertificate` object contains the specified SHA hash. */ public shaCertificate(shaHash: string): ShaCertificate { return new ShaCertificate(shaHash); @@ -117,7 +114,7 @@ export class ProjectManagement { * @param displayName An optional user-assigned display name for this * new app. * - * @return A promise that resolves to the newly created Android app. + * @returns A promise that resolves to the newly created Android app. */ public createAndroidApp(packageName: string, displayName?: string): Promise { return this.getResourceName() @@ -145,7 +142,7 @@ export class ProjectManagement { * @param displayName An optional user-assigned display name for this * new app. * - * @return A promise that resolves to the newly created iOS app. + * @returns A promise that resolves to the newly created iOS app. */ public createIosApp(bundleId: string, displayName?: string): Promise { return this.getResourceName() @@ -169,7 +166,7 @@ export class ProjectManagement { /** * Lists up to 100 Firebase apps associated with this Firebase project. * - * @return A promise that resolves to the metadata list of the apps. + * @returns A promise that resolves to the metadata list of the apps. */ public listAppMetadata(): Promise { return this.getResourceName() @@ -189,7 +186,7 @@ export class ProjectManagement { * * @param newDisplayName The new display name to be updated. * - * @return A promise that resolves when the project display name has been updated. + * @returns A promise that resolves when the project display name has been updated. */ public setDisplayName(newDisplayName: string): Promise { return this.getResourceName() diff --git a/src/remote-config/index.ts b/src/remote-config/index.ts index 0d0d6e6612..24c8a1fa4e 100644 --- a/src/remote-config/index.ts +++ b/src/remote-config/index.ts @@ -35,14 +35,11 @@ export { export { RemoteConfig } from './remote-config'; /** - * Gets the {@link remoteConfig.RemoteConfig `RemoteConfig`} service for the - * default app or a given app. + * Gets the {@link RemoteConfig} service for the default app or a given app. * * `getRemoteConfig()` can be called with no arguments to access the default - * app's {@link remoteConfig.RemoteConfig `RemoteConfig`} service or as - * `getRemoteConfig(app)` to access the - * {@link remoteConfig.RemoteConfig `RemoteConfig`} service associated with a - * specific app. + * app's `RemoteConfig` service or as `getRemoteConfig(app)` to access the + * `RemoteConfig` service associated with a specific app. * * @example * ```javascript @@ -59,7 +56,7 @@ export { RemoteConfig } from './remote-config'; * @param app Optional app for which to return the `RemoteConfig` service. * If not provided, the default `RemoteConfig` service is returned. * - * @return The default `RemoteConfig` service if no + * @returns The default `RemoteConfig` service if no * app is provided, or the `RemoteConfig` service associated with the provided * app. */ diff --git a/src/remote-config/remote-config-api-client-internal.ts b/src/remote-config/remote-config-api-client-internal.ts index 1e91b497f3..9ea77bb532 100644 --- a/src/remote-config/remote-config-api-client-internal.ts +++ b/src/remote-config/remote-config-api-client-internal.ts @@ -336,7 +336,7 @@ export class RemoteConfigApiClient { * * @param {ListVersionsOptions} options An options object to be validated. * - * @return {ListVersionsOptions} A copy of the provided options object with timestamps converted + * @returns {ListVersionsOptions} A copy of the provided options object with timestamps converted * to UTC Zulu format. */ private validateListVersionsOptions(options: ListVersionsOptions): ListVersionsOptions { diff --git a/src/remote-config/remote-config-api.ts b/src/remote-config/remote-config-api.ts index 9493e855d8..b8d49640c7 100644 --- a/src/remote-config/remote-config-api.ts +++ b/src/remote-config/remote-config-api.ts @@ -35,7 +35,7 @@ export interface RemoteConfigCondition { /** * The logic of this condition. * See the documentation on - * {@link https://firebase.google.com/docs/remote-config/condition-reference condition expressions} + * {@link https://firebase.google.com/docs/remote-config/condition-reference | condition expressions} * for the expected syntax of this field. */ expression: string; diff --git a/src/remote-config/remote-config-namespace.ts b/src/remote-config/remote-config-namespace.ts index d50fcb0aee..39839c6f07 100644 --- a/src/remote-config/remote-config-namespace.ts +++ b/src/remote-config/remote-config-namespace.ts @@ -32,14 +32,12 @@ import { import { RemoteConfig as TRemoteConfig } from './remote-config'; /** - * Gets the {@link remoteConfig.RemoteConfig `RemoteConfig`} service for the + * Gets the {@link firebase-admin.remote-config#RemoteConfig} service for the * default app or a given app. * * `admin.remoteConfig()` can be called with no arguments to access the default - * app's {@link remoteConfig.RemoteConfig `RemoteConfig`} service or as - * `admin.remoteConfig(app)` to access the - * {@link remoteConfig.RemoteConfig `RemoteConfig`} service associated with a - * specific app. + * app's `RemoteConfig` service or as `admin.remoteConfig(app)` to access the + * `RemoteConfig` service associated with a specific app. * * @example * ```javascript @@ -56,7 +54,7 @@ import { RemoteConfig as TRemoteConfig } from './remote-config'; * @param app Optional app for which to return the `RemoteConfig` service. * If not provided, the default `RemoteConfig` service is returned. * - * @return The default `RemoteConfig` service if no + * @returns The default `RemoteConfig` service if no * app is provided, or the `RemoteConfig` service associated with the provided * app. */ diff --git a/src/remote-config/remote-config.ts b/src/remote-config/remote-config.ts index c6b23517ef..2b35a216a2 100644 --- a/src/remote-config/remote-config.ts +++ b/src/remote-config/remote-config.ts @@ -45,10 +45,9 @@ export class RemoteConfig { } /** - * Gets the current active version of the {@link remoteConfig.RemoteConfigTemplate - * `RemoteConfigTemplate`} of the project. + * Gets the current active version of the {@link RemoteConfigTemplate} of the project. * - * @return A promise that fulfills with a `RemoteConfigTemplate`. + * @returns A promise that fulfills with a `RemoteConfigTemplate`. */ public getTemplate(): Promise { return this.client.getTemplate() @@ -58,12 +57,11 @@ export class RemoteConfig { } /** - * Gets the requested version of the {@link remoteConfig.RemoteConfigTemplate - * `RemoteConfigTemplate`} of the project. + * Gets the requested version of the {@link RemoteConfigTemplate} of the project. * * @param versionNumber Version number of the Remote Config template to look up. * - * @return A promise that fulfills with a `RemoteConfigTemplate`. + * @returns A promise that fulfills with a `RemoteConfigTemplate`. */ public getTemplateAtVersion(versionNumber: number | string): Promise { return this.client.getTemplateAtVersion(versionNumber) @@ -73,7 +71,7 @@ export class RemoteConfig { } /** - * Validates a {@link remoteConfig.RemoteConfigTemplate `RemoteConfigTemplate`}. + * Validates a {@link RemoteConfigTemplate}. * * @param template The Remote Config template to be validated. * @returns A promise that fulfills with the validated `RemoteConfigTemplate`. @@ -90,14 +88,14 @@ export class RemoteConfig { * * @param template The Remote Config template to be published. * @param options Optional options object when publishing a Remote Config template: - * - {boolean} `force` Setting this to `true` forces the Remote Config template to + * - `force`: Setting this to `true` forces the Remote Config template to * be updated and circumvent the ETag. This approach is not recommended * because it risks causing the loss of updates to your Remote Config * template if multiple clients are updating the Remote Config template. - * See {@link https://firebase.google.com/docs/remote-config/use-config-rest#etag_usage_and_forced_updates + * See {@link https://firebase.google.com/docs/remote-config/use-config-rest#etag_usage_and_forced_updates | * ETag usage and forced updates}. * - * @return A Promise that fulfills with the published `RemoteConfigTemplate`. + * @returns A Promise that fulfills with the published `RemoteConfigTemplate`. */ public publishTemplate(template: RemoteConfigTemplate, options?: { force: boolean }): Promise { return this.client.publishTemplate(template, options) @@ -116,7 +114,7 @@ export class RemoteConfig { * been deleted due to staleness. Only the last 300 versions are stored. * All versions that correspond to non-active Remote Config templates (that is, all except the * template that is being fetched by clients) are also deleted if they are more than 90 days old. - * @return A promise that fulfills with the published `RemoteConfigTemplate`. + * @returns A promise that fulfills with the published `RemoteConfigTemplate`. */ public rollback(versionNumber: number | string): Promise { return this.client.rollback(versionNumber) @@ -132,7 +130,7 @@ export class RemoteConfig { * template that is being fetched by clients) are also deleted if they are older than 90 days. * * @param options Optional options object for getting a list of versions. - * @return A promise that fulfills with a `ListVersionsResult`. + * @returns A promise that fulfills with a `ListVersionsResult`. */ public listVersions(options?: ListVersionsOptions): Promise { return this.client.listVersions(options) @@ -149,7 +147,7 @@ export class RemoteConfig { * * @param json The JSON string to populate a Remote Config template. * - * @return A new template instance. + * @returns A new template instance. */ public createTemplateFromJSON(json: string): RemoteConfigTemplate { if (!validator.isNonEmptyString(json)) { @@ -234,14 +232,16 @@ class RemoteConfigTemplateImpl implements RemoteConfigTemplate { /** * Gets the ETag of the template. * - * @return The ETag of the Remote Config template. + * @returns The ETag of the Remote Config template. */ get etag(): string { return this.etagInternal; } /** - * @return A JSON-serializable representation of this object. + * Returns a JSON-serializable representation of this object. + * + * @returns A JSON-serializable representation of this object. */ public toJSON(): object { return { @@ -359,7 +359,7 @@ class VersionImpl implements Version { } /** - * @return A JSON-serializable representation of this object. + * @returns A JSON-serializable representation of this object. */ public toJSON(): object { return { diff --git a/src/security-rules/index.ts b/src/security-rules/index.ts index 3537f6bf6a..11770d381d 100644 --- a/src/security-rules/index.ts +++ b/src/security-rules/index.ts @@ -27,14 +27,11 @@ export { } from './security-rules'; /** - * Gets the {@link securityRules.SecurityRules - * `SecurityRules`} service for the default app or a given app. + * Gets the {@link SecurityRules} service for the default app or a given app. * * `admin.securityRules()` can be called with no arguments to access the - * default app's {@link securityRules.SecurityRules - * `SecurityRules`} service, or as `admin.securityRules(app)` to access - * the {@link securityRules.SecurityRules `SecurityRules`} - * service associated with a specific app. + * default app's `SecurityRules` service, or as `admin.securityRules(app)` to access + * the `SecurityRules` service associated with a specific app. * * @example * ```javascript @@ -51,7 +48,7 @@ export { * @param app Optional app to return the `SecurityRules` service * for. If not provided, the default `SecurityRules` service * is returned. - * @return The default `SecurityRules` service if no app is provided, or the + * @returns The default `SecurityRules` service if no app is provided, or the * `SecurityRules` service associated with the provided app. */ export function getSecurityRules(app?: App): SecurityRules { diff --git a/src/security-rules/security-rules-namespace.ts b/src/security-rules/security-rules-namespace.ts index 6556440f54..dfcd1fffe1 100644 --- a/src/security-rules/security-rules-namespace.ts +++ b/src/security-rules/security-rules-namespace.ts @@ -48,7 +48,7 @@ import { * @param app Optional app to return the `SecurityRules` service * for. If not provided, the default `SecurityRules` service * is returned. - * @return The default `SecurityRules` service if no app is provided, or the + * @returns The default `SecurityRules` service if no app is provided, or the * `SecurityRules` service associated with the provided app. */ export declare function securityRules(app?: App): securityRules.SecurityRules; diff --git a/src/security-rules/security-rules.ts b/src/security-rules/security-rules.ts index 83c49b9e86..6a5eafa3d9 100644 --- a/src/security-rules/security-rules.ts +++ b/src/security-rules/security-rules.ts @@ -24,8 +24,7 @@ import { FirebaseSecurityRulesError } from './security-rules-internal'; /** * A source file containing some Firebase security rules. The content includes raw * source code including text formatting, indentation and comments. Use the - * [`securityRules.createRulesFileFromSource()`](securityRules.SecurityRules#createRulesFileFromSource) - * method to create new instances of this type. + * {@link SecurityRules.createRulesFileFromSource} method to create new instances of this type. */ export interface RulesFile { readonly name: string; @@ -38,8 +37,7 @@ export interface RulesFile { export interface RulesetMetadata { /** * Name of the `Ruleset` as a short string. This can be directly passed into APIs - * like {@link securityRules.SecurityRules.getRuleset `securityRules.getRuleset()`} - * and {@link securityRules.SecurityRules.deleteRuleset `securityRules.deleteRuleset()`}. + * like {@link SecurityRules.getRuleset} and {@link SecurityRules.deleteRuleset}. */ readonly name: string; /** @@ -142,14 +140,14 @@ export class SecurityRules { } /** - * Gets the {@link securityRules.Ruleset `Ruleset`} identified by the given + * Gets the {@link Ruleset} identified by the given * name. The input name should be the short name string without the project ID * prefix. For example, to retrieve the `projects/project-id/rulesets/my-ruleset`, * pass the short name "my-ruleset". Rejects with a `not-found` error if the * specified `Ruleset` cannot be found. * * @param name Name of the `Ruleset` to retrieve. - * @return A promise that fulfills with the specified `Ruleset`. + * @returns A promise that fulfills with the specified `Ruleset`. */ public getRuleset(name: string): Promise { return this.client.getRuleset(name) @@ -159,22 +157,22 @@ export class SecurityRules { } /** - * Gets the {@link securityRules.Ruleset `Ruleset`} currently applied to + * Gets the {@link Ruleset} currently applied to * Cloud Firestore. Rejects with a `not-found` error if no ruleset is applied * on Firestore. * - * @return A promise that fulfills with the Firestore ruleset. + * @returns A promise that fulfills with the Firestore ruleset. */ public getFirestoreRuleset(): Promise { return this.getRulesetForRelease(SecurityRules.CLOUD_FIRESTORE); } /** - * Creates a new {@link securityRules.Ruleset `Ruleset`} from the given + * Creates a new {@link Ruleset} from the given * source, and applies it to Cloud Firestore. * * @param source Rules source to apply. - * @return A promise that fulfills when the ruleset is created and released. + * @returns A promise that fulfills when the ruleset is created and released. */ public releaseFirestoreRulesetFromSource(source: string | Buffer): Promise { return Promise.resolve() @@ -191,26 +189,26 @@ export class SecurityRules { } /** - * Applies the specified {@link securityRules.Ruleset `Ruleset`} ruleset + * Applies the specified {@link Ruleset} ruleset * to Cloud Firestore. * * @param ruleset Name of the ruleset to apply or a `RulesetMetadata` object * containing the name. - * @return A promise that fulfills when the ruleset is released. + * @returns A promise that fulfills when the ruleset is released. */ public releaseFirestoreRuleset(ruleset: string | RulesetMetadata): Promise { return this.releaseRuleset(ruleset, SecurityRules.CLOUD_FIRESTORE); } /** - * Gets the {@link securityRules.Ruleset `Ruleset`} currently applied to a + * Gets the {@link Ruleset} currently applied to a * Cloud Storage bucket. Rejects with a `not-found` error if no ruleset is applied * on the bucket. * * @param bucket Optional name of the Cloud Storage bucket to be retrieved. If not * specified, retrieves the ruleset applied on the default bucket configured via * `AppOptions`. - * @return A promise that fulfills with the Cloud Storage ruleset. + * @returns A promise that fulfills with the Cloud Storage ruleset. */ public getStorageRuleset(bucket?: string): Promise { return Promise.resolve() @@ -223,14 +221,14 @@ export class SecurityRules { } /** - * Creates a new {@link securityRules.Ruleset `Ruleset`} from the given + * Creates a new {@link Ruleset} from the given * source, and applies it to a Cloud Storage bucket. * * @param source Rules source to apply. * @param bucket Optional name of the Cloud Storage bucket to apply the rules on. If * not specified, applies the ruleset on the default bucket configured via - * {@link AppOptions `AppOptions`}. - * @return A promise that fulfills when the ruleset is created and released. + * {@link firebase-admin.app#AppOptions}. + * @returns A promise that fulfills when the ruleset is created and released. */ public releaseStorageRulesetFromSource(source: string | Buffer, bucket?: string): Promise { return Promise.resolve() @@ -250,15 +248,15 @@ export class SecurityRules { } /** - * Applies the specified {@link securityRules.Ruleset `Ruleset`} ruleset + * Applies the specified {@link Ruleset} ruleset * to a Cloud Storage bucket. * * @param ruleset Name of the ruleset to apply or a `RulesetMetadata` object * containing the name. * @param bucket Optional name of the Cloud Storage bucket to apply the rules on. If * not specified, applies the ruleset on the default bucket configured via - * {@link AppOptions `AppOptions`}. - * @return A promise that fulfills when the ruleset is released. + * {@link firebase-admin.app#AppOptions}. + * @returns A promise that fulfills when the ruleset is released. */ public releaseStorageRuleset(ruleset: string | RulesetMetadata, bucket?: string): Promise { return Promise.resolve() @@ -271,7 +269,7 @@ export class SecurityRules { } /** - * Creates a {@link securityRules.RulesFile `RuleFile`} with the given name + * Creates a {@link RulesFile} with the given name * and source. Throws an error if any of the arguments are invalid. This is a local * operation, and does not involve any network API calls. * @@ -285,7 +283,7 @@ export class SecurityRules { * @param name Name to assign to the rules file. This is usually a short file name that * helps identify the file in a ruleset. * @param source Contents of the rules file. - * @return A new rules file instance. + * @returns A new rules file instance. */ public createRulesFileFromSource(name: string, source: string | Buffer): RulesFile { if (!validator.isNonEmptyString(name)) { @@ -310,8 +308,7 @@ export class SecurityRules { } /** - * Creates a new {@link securityRules.Ruleset `Ruleset`} from the given - * {@link securityRules.RulesFile `RuleFile`}. + * Creates a new {@link Ruleset} from the given {@link RulesFile}. * * @param file Rules file to include in the new `Ruleset`. * @returns A promise that fulfills with the newly created `Ruleset`. @@ -330,14 +327,14 @@ export class SecurityRules { } /** - * Deletes the {@link securityRules.Ruleset `Ruleset`} identified by the given + * Deletes the {@link Ruleset} identified by the given * name. The input name should be the short name string without the project ID * prefix. For example, to delete the `projects/project-id/rulesets/my-ruleset`, * pass the short name "my-ruleset". Rejects with a `not-found` error if the * specified `Ruleset` cannot be found. * * @param name Name of the `Ruleset` to delete. - * @return A promise that fulfills when the `Ruleset` is deleted. + * @returns A promise that fulfills when the `Ruleset` is deleted. */ public deleteRuleset(name: string): Promise { return this.client.deleteRuleset(name); @@ -350,7 +347,7 @@ export class SecurityRules { * limit. * @param nextPageToken The next page token. If not specified, returns rulesets * starting without any offset. - * @return A promise that fulfills with a page of rulesets. + * @returns A promise that fulfills with a page of rulesets. */ public listRulesetMetadata(pageSize = 100, nextPageToken?: string): Promise { return this.client.listRulesets(pageSize, nextPageToken) diff --git a/src/storage/index.ts b/src/storage/index.ts index 6eeca2a107..878174afa2 100644 --- a/src/storage/index.ts +++ b/src/storage/index.ts @@ -21,14 +21,11 @@ import { Storage } from './storage'; export { Storage } from './storage'; /** - * Gets the {@link storage.Storage `Storage`} service for the - * default app or a given app. + * Gets the {@link Storage} service for the default app or a given app. * * `getStorage()` can be called with no arguments to access the default - * app's {@link storage.Storage `Storage`} service or as - * `getStorage(app)` to access the - * {@link storage.Storage `Storage`} service associated with a - * specific app. + * app's `Storage` service or as `getStorage(app)` to access the + * `Storage` service associated with a specific app. * * @example * ```javascript diff --git a/src/storage/storage-namespace.ts b/src/storage/storage-namespace.ts index 1e78d076d6..26ebddf72c 100644 --- a/src/storage/storage-namespace.ts +++ b/src/storage/storage-namespace.ts @@ -18,14 +18,12 @@ import { App } from '../app'; import { Storage as TStorage } from './storage'; /** - * Gets the {@link storage.Storage `Storage`} service for the + * Gets the {@link firebase-admin.storage#Storage} service for the * default app or a given app. * * `admin.storage()` can be called with no arguments to access the default - * app's {@link storage.Storage `Storage`} service or as - * `admin.storage(app)` to access the - * {@link storage.Storage `Storage`} service associated with a - * specific app. + * app's `Storage` service or as `admin.storage(app)` to access the + * `Storage` service associated with a specific app. * * @example * ```javascript diff --git a/src/storage/storage.ts b/src/storage/storage.ts index dc36b72f52..5aebb7c4b4 100644 --- a/src/storage/storage.ts +++ b/src/storage/storage.ts @@ -48,7 +48,7 @@ export class Storage { if (!process.env.STORAGE_EMULATOR_HOST && process.env.FIREBASE_STORAGE_EMULATOR_HOST) { process.env.STORAGE_EMULATOR_HOST = process.env.FIREBASE_STORAGE_EMULATOR_HOST; } - + let storage: typeof StorageClient; try { storage = require('@google-cloud/storage').Storage; @@ -92,7 +92,7 @@ export class Storage { * * @param name Optional name of the bucket to be retrieved. If name is not specified, * retrieves a reference to the default bucket. - * @returns A [Bucket](https://cloud.google.com/nodejs/docs/reference/storage/latest/Bucket) + * @returns A {@link https://cloud.google.com/nodejs/docs/reference/storage/latest/Bucket | Bucket} * instance as defined in the `@google-cloud/storage` package. */ public bucket(name?: string): Bucket { diff --git a/src/utils/api-request.ts b/src/utils/api-request.ts index 221a5221f2..dfad60b937 100644 --- a/src/utils/api-request.ts +++ b/src/utils/api-request.ts @@ -260,8 +260,8 @@ export class HttpClient { * header should be explicitly set by the caller. To send a JSON leaf value (e.g. "foo", 5), parse it into JSON, * and pass as a string or a Buffer along with the appropriate content-type header. * - * @param {HttpRequest} config HTTP request to be sent. - * @return {Promise} A promise that resolves with the response details. + * @param config HTTP request to be sent. + * @returns A promise that resolves with the response details. */ public send(config: HttpRequestConfig): Promise { return this.sendWithRetry(config); @@ -271,9 +271,9 @@ export class HttpClient { * Sends an HTTP request. In the event of an error, retries the HTTP request according to the * RetryConfig set on the HttpClient. * - * @param {HttpRequestConfig} config HTTP request to be sent. - * @param {number} retryAttempts Number of retries performed up to now. - * @return {Promise} A promise that resolves with the response details. + * @param config HTTP request to be sent. + * @param retryAttempts Number of retries performed up to now. + * @returns A promise that resolves with the response details. */ private sendWithRetry(config: HttpRequestConfig, retryAttempts = 0): Promise { return AsyncHttpCall.invoke(config) @@ -323,9 +323,9 @@ export class HttpClient { * Checks if a failed request is eligible for a retry, and if so returns the duration to wait before initiating * the retry. * - * @param {number} retryAttempts Number of retries completed up to now. - * @param {LowLevelError} err The last encountered error. - * @returns {[number, boolean]} A 2-tuple where the 1st element is the duration to wait before another retry, and the + * @param retryAttempts Number of retries completed up to now. + * @param err The last encountered error. + * @returns A 2-tuple where the 1st element is the duration to wait before another retry, and the * 2nd element is a boolean indicating whether the request is eligible for a retry or not. */ private getRetryDelayMillis(retryAttempts: number, err: LowLevelError): [number, boolean] { @@ -401,9 +401,9 @@ export class HttpClient { /** * Parses a full HTTP response message containing both a header and a body. * - * @param {string|Buffer} response The HTTP response to be parsed. - * @param {HttpRequestConfig} config The request configuration that resulted in the HTTP response. - * @return {HttpResponse} An object containing the parsed HTTP status, headers and the body. + * @param response The HTTP response to be parsed. + * @param config The request configuration that resulted in the HTTP response. + * @returns An object containing the parsed HTTP status, headers and the body. */ export function parseHttpResponse( response: string | Buffer, config: HttpRequestConfig): HttpResponse { @@ -839,8 +839,8 @@ export class AuthorizedHttpClient extends HttpClient { /** * Class that defines all the settings for the backend API endpoint. * - * @param {string} endpoint The Firebase Auth backend endpoint. - * @param {HttpMethod} httpMethod The http method for that endpoint. + * @param endpoint The Firebase Auth backend endpoint. + * @param httpMethod The http method for that endpoint. * @constructor */ export class ApiSettings { @@ -852,19 +852,19 @@ export class ApiSettings { .setResponseValidator(null); } - /** @return {string} The backend API endpoint. */ + /** @returns The backend API endpoint. */ public getEndpoint(): string { return this.endpoint; } - /** @return {HttpMethod} The request HTTP method. */ + /** @returns The request HTTP method. */ public getHttpMethod(): HttpMethod { return this.httpMethod; } /** - * @param {ApiCallbackFunction} requestValidator The request validator. - * @return {ApiSettings} The current API settings instance. + * @param requestValidator The request validator. + * @returns The current API settings instance. */ public setRequestValidator(requestValidator: ApiCallbackFunction | null): ApiSettings { const nullFunction: ApiCallbackFunction = () => undefined; @@ -872,14 +872,14 @@ export class ApiSettings { return this; } - /** @return {ApiCallbackFunction} The request validator. */ + /** @returns The request validator. */ public getRequestValidator(): ApiCallbackFunction { return this.requestValidator; } /** - * @param {ApiCallbackFunction} responseValidator The response validator. - * @return {ApiSettings} The current API settings instance. + * @param responseValidator The response validator. + * @returns The current API settings instance. */ public setResponseValidator(responseValidator: ApiCallbackFunction | null): ApiSettings { const nullFunction: ApiCallbackFunction = () => undefined; @@ -887,7 +887,7 @@ export class ApiSettings { return this; } - /** @return {ApiCallbackFunction} The response validator. */ + /** @returns The response validator. */ public getResponseValidator(): ApiCallbackFunction { return this.responseValidator; } @@ -938,10 +938,10 @@ export class ExponentialBackoffPoller extends EventEmitter { /** * Poll the provided callback with exponential backoff. * - * @param {() => Promise} callback The callback to be called for each poll. If the + * @param callback The callback to be called for each poll. If the * callback resolves to a falsey value, polling will continue. Otherwise, the truthy * resolution will be used to resolve the promise returned by this method. - * @return {Promise} A Promise which resolves to the truthy value returned by the provided + * @returns A Promise which resolves to the truthy value returned by the provided * callback when polling is complete. */ public poll(callback: () => Promise): Promise { diff --git a/src/utils/deep-copy.ts b/src/utils/deep-copy.ts index 8e5bee9d8b..4b73e7da8f 100644 --- a/src/utils/deep-copy.ts +++ b/src/utils/deep-copy.ts @@ -18,8 +18,8 @@ /** * Returns a deep copy of an object or array. * - * @param {object|array} value The object or array to deep copy. - * @return {object|array} A deep copy of the provided object or array. + * @param value The object or array to deep copy. + * @returns A deep copy of the provided object or array. */ export function deepCopy(value: T): T { return deepExtend(undefined, value); @@ -37,9 +37,9 @@ export function deepCopy(value: T): T { * Note that the target can be a function, in which case the properties in the source object are * copied onto it as static properties of the function. * - * @param {any} target The value which is being extended. - * @param {any} source The value whose properties are extending the target. - * @return {any} The target value. + * @param target The value which is being extended. + * @param source The value whose properties are extending the target. + * @returns The target value. */ export function deepExtend(target: any, source: any): any { if (!(source instanceof Object)) { diff --git a/src/utils/error.ts b/src/utils/error.ts index 91fe79debb..2953d9148e 100644 --- a/src/utils/error.ts +++ b/src/utils/error.ts @@ -36,7 +36,7 @@ interface ServerToClientCode { /** * Firebase error code structure. This extends Error. * - * @param {ErrorInfo} errorInfo The error information (code and message). + * @param errorInfo The error information (code and message). * @constructor */ export class FirebaseError extends Error implements FirebaseErrorInterface { @@ -50,17 +50,17 @@ export class FirebaseError extends Error implements FirebaseErrorInterface { (this as any).__proto__ = FirebaseError.prototype; } - /** @return {string} The error code. */ + /** @returns The error code. */ public get code(): string { return this.errorInfo.code; } - /** @return {string} The error message. */ + /** @returns The error message. */ public get message(): string { return this.errorInfo.message; } - /** @return {object} The object representation of the error. */ + /** @returns The object representation of the error. */ public toJSON(): object { return { code: this.code, @@ -72,9 +72,9 @@ export class FirebaseError extends Error implements FirebaseErrorInterface { /** * A FirebaseError with a prefix in front of the error code. * - * @param {string} codePrefix The prefix to apply to the error code. - * @param {string} code The error code. - * @param {string} message The error message. + * @param codePrefix The prefix to apply to the error code. + * @param code The error code. + * @param message The error message. * @constructor */ export class PrefixedFirebaseError extends FirebaseError { @@ -95,8 +95,8 @@ export class PrefixedFirebaseError extends FirebaseError { * Allows the error type to be checked without needing to know implementation details * of the code prefixing. * - * @param {string} code The non-prefixed error code to test against. - * @return {boolean} True if the code matches, false otherwise. + * @param code The non-prefixed error code to test against. + * @returns True if the code matches, false otherwise. */ public hasCode(code: string): boolean { return `${this.codePrefix}/${code}` === this.code; @@ -106,8 +106,8 @@ export class PrefixedFirebaseError extends FirebaseError { /** * Firebase App error code structure. This extends PrefixedFirebaseError. * - * @param {string} code The error code. - * @param {string} message The error message. + * @param code The error code. + * @param message The error message. * @constructor */ export class FirebaseAppError extends PrefixedFirebaseError { @@ -125,8 +125,8 @@ export class FirebaseAppError extends PrefixedFirebaseError { /** * Firebase Auth error code structure. This extends PrefixedFirebaseError. * - * @param {ErrorInfo} info The error code info. - * @param {string} [message] The error message. This will override the default + * @param info The error code info. + * @param [message] The error message. This will override the default * message if provided. * @constructor */ @@ -134,11 +134,11 @@ export class FirebaseAuthError extends PrefixedFirebaseError { /** * Creates the developer-facing error corresponding to the backend error code. * - * @param {string} serverErrorCode The server error code. - * @param {string} [message] The error message. The default message is used + * @param serverErrorCode The server error code. + * @param [message] The error message. The default message is used * if not provided. - * @param {object} [rawServerResponse] The error's raw server response. - * @return {FirebaseAuthError} The corresponding developer-facing error. + * @param [rawServerResponse] The error's raw server response. + * @returns The corresponding developer-facing error. */ public static fromServerError( serverErrorCode: string, @@ -185,8 +185,8 @@ export class FirebaseAuthError extends PrefixedFirebaseError { /** * Firebase Database error code structure. This extends FirebaseError. * - * @param {ErrorInfo} info The error code info. - * @param {string} [message] The error message. This will override the default + * @param info The error code info. + * @param [message] The error message. This will override the default * message if provided. * @constructor */ @@ -200,8 +200,8 @@ export class FirebaseDatabaseError extends FirebaseError { /** * Firebase Firestore error code structure. This extends FirebaseError. * - * @param {ErrorInfo} info The error code info. - * @param {string} [message] The error message. This will override the default + * @param info The error code info. + * @param [message] The error message. This will override the default * message if provided. * @constructor */ @@ -215,8 +215,8 @@ export class FirebaseFirestoreError extends FirebaseError { /** * Firebase instance ID error code structure. This extends FirebaseError. * - * @param {ErrorInfo} info The error code info. - * @param {string} [message] The error message. This will override the default + * @param info The error code info. + * @param [message] The error message. This will override the default * message if provided. * @constructor */ @@ -231,19 +231,19 @@ export class FirebaseInstanceIdError extends FirebaseError { /** * Firebase Messaging error code structure. This extends PrefixedFirebaseError. * - * @param {ErrorInfo} info The error code info. - * @param {string} [message] The error message. This will override the default message if provided. + * @param info The error code info. + * @param [message] The error message. This will override the default message if provided. * @constructor */ export class FirebaseMessagingError extends PrefixedFirebaseError { /** * Creates the developer-facing error corresponding to the backend error code. * - * @param {string} serverErrorCode The server error code. - * @param {string} [message] The error message. The default message is used + * @param serverErrorCode The server error code. + * @param [message] The error message. The default message is used * if not provided. - * @param {object} [rawServerResponse] The error's raw server response. - * @return {FirebaseMessagingError} The corresponding developer-facing error. + * @param [rawServerResponse] The error's raw server response. + * @returns The corresponding developer-facing error. */ public static fromServerError( serverErrorCode: string | null, @@ -305,8 +305,8 @@ export class FirebaseMessagingError extends PrefixedFirebaseError { /** * Firebase project management error code structure. This extends PrefixedFirebaseError. * - * @param {ProjectManagementErrorCode} code The error code. - * @param {string} message The error message. + * @param code The error code. + * @param message The error message. * @constructor */ export class FirebaseProjectManagementError extends PrefixedFirebaseError { diff --git a/src/utils/index.ts b/src/utils/index.ts index 559574fb47..372dc6a5a6 100644 --- a/src/utils/index.ts +++ b/src/utils/index.ts @@ -37,8 +37,8 @@ export function getSdkVersion(): string { * * For example, this can be used to map underscore_cased properties to camelCase. * - * @param {object} obj The object whose properties to rename. - * @param {object} keyMap The mapping from old to new property names. + * @param obj The object whose properties to rename. + * @param keyMap The mapping from old to new property names. */ export function renameProperties(obj: {[key: string]: any}, keyMap: { [key: string]: string }): void { Object.keys(keyMap).forEach((oldKey) => { @@ -54,9 +54,9 @@ export function renameProperties(obj: {[key: string]: any}, keyMap: { [key: stri /** * Defines a new read-only property directly on an object and returns the object. * - * @param {object} obj The object on which to define the property. - * @param {string} prop The name of the property to be defined or modified. - * @param {any} value The value associated with the property. + * @param obj The object on which to define the property. + * @param prop The name of the property to be defined or modified. + * @param value The value associated with the property. */ export function addReadonlyGetter(obj: object, prop: string, value: any): void { Object.defineProperty(obj, prop, { @@ -75,7 +75,7 @@ export function addReadonlyGetter(obj: object, prop: string, value: any): void { * * @param app A Firebase app to get the project ID from. * - * @return A project ID string or null. + * @returns A project ID string or null. */ export function getExplicitProjectId(app: App): string | null { const options = app.options; @@ -104,7 +104,7 @@ export function getExplicitProjectId(app: App): string | null { * * @param app A Firebase app to get the project ID from. * - * @return A project ID string or null. + * @returns A project ID string or null. */ export function findProjectId(app: App): Promise { const projectId = getExplicitProjectId(app); @@ -123,8 +123,8 @@ export function findProjectId(app: App): Promise { /** * Encodes data using web-safe-base64. * - * @param {Buffer} data The raw data byte input. - * @return {string} The base64-encoded result. + * @param data The raw data byte input. + * @returns The base64-encoded result. */ export function toWebSafeBase64(data: Buffer): string { return data.toString('base64').replace(/\//g, '_').replace(/\+/g, '-'); @@ -135,11 +135,11 @@ export function toWebSafeBase64(data: Buffer): string { * with corresponding arguments {projectId: '1234', api: 'resource'} * and returns output: 'project/1234/resource'. * - * @param {string} str The original string where the param need to be + * @param str The original string where the param need to be * replaced. - * @param {object=} params The optional parameters to replace in the + * @param params The optional parameters to replace in the * string. - * @return {string} The resulting formatted string. + * @returns The resulting formatted string. */ export function formatString(str: string, params?: object): string { let formatted = str; @@ -160,7 +160,7 @@ export function formatString(str: string, params?: object): string { * Nested objects beyond that path will be ignored. This is useful for * keys with variable object values. * @param root The path so far. - * @return The computed update mask list. + * @returns The computed update mask list. */ export function generateUpdateMask( obj: any, terminalPaths: string[] = [], root = '' diff --git a/src/utils/jwt.ts b/src/utils/jwt.ts index d048567061..6ca56dabc6 100644 --- a/src/utils/jwt.ts +++ b/src/utils/jwt.ts @@ -62,7 +62,7 @@ export class UrlKeyFetcher implements KeyFetcher { /** * Fetches the public keys for the Google certs. * - * @return A promise fulfilled with public keys for the Google certs. + * @returns A promise fulfilled with public keys for the Google certs. */ public fetchPublicKeys(): Promise<{ [key: string]: string }> { if (this.shouldRefresh()) { @@ -73,7 +73,7 @@ export class UrlKeyFetcher implements KeyFetcher { /** * Checks if the cached public keys need to be refreshed. - * + * * @returns Whether the keys should be fetched from the client certs url or not. */ private shouldRefresh(): boolean { @@ -163,7 +163,7 @@ export class EmulatorSignatureVerifier implements SignatureVerifier { /** * Provides a callback to fetch public keys. - * + * * @param fetcher KeyFetcher to fetch the keys from. * @returns A callback function that can be used to get keys in `jsonwebtoken`. */ @@ -186,7 +186,7 @@ function getKeyCallback(fetcher: KeyFetcher): jwt.GetPublicKeyOrSecret { /** * Verifies the signature of a JWT using the provided secret or a function to fetch * the secret or public key. - * + * * @param token The JWT to be verfied. * @param secretOrPublicKey The secret or a function to fetch the secret or public key. * @param options JWT verification options. @@ -224,7 +224,7 @@ export function verifyJwtSignature(token: string, secretOrPublicKey: jwt.Secret /** * Decodes general purpose Firebase JWTs. - * + * * @param jwtToken JWT token to be decoded. * @returns Decoded token containing the header and payload. */ diff --git a/src/utils/validator.ts b/src/utils/validator.ts index bca0c660ab..523f91f33c 100644 --- a/src/utils/validator.ts +++ b/src/utils/validator.ts @@ -20,8 +20,8 @@ import url = require('url'); /** * Validates that a value is a byte buffer. * - * @param {any} value The value to validate. - * @return {boolean} Whether the value is byte buffer or not. + * @param value The value to validate. + * @returns Whether the value is byte buffer or not. */ export function isBuffer(value: any): value is Buffer { return value instanceof Buffer; @@ -30,8 +30,8 @@ export function isBuffer(value: any): value is Buffer { /** * Validates that a value is an array. * - * @param {any} value The value to validate. - * @return {boolean} Whether the value is an array or not. + * @param value The value to validate. + * @returns Whether the value is an array or not. */ export function isArray(value: any): value is T[] { return Array.isArray(value); @@ -40,8 +40,8 @@ export function isArray(value: any): value is T[] { /** * Validates that a value is a non-empty array. * - * @param {any} value The value to validate. - * @return {boolean} Whether the value is a non-empty array or not. + * @param value The value to validate. + * @returns Whether the value is a non-empty array or not. */ export function isNonEmptyArray(value: any): value is T[] { return isArray(value) && value.length !== 0; @@ -51,8 +51,8 @@ export function isNonEmptyArray(value: any): value is T[] { /** * Validates that a value is a boolean. * - * @param {any} value The value to validate. - * @return {boolean} Whether the value is a boolean or not. + * @param value The value to validate. + * @returns Whether the value is a boolean or not. */ export function isBoolean(value: any): boolean { return typeof value === 'boolean'; @@ -62,8 +62,8 @@ export function isBoolean(value: any): boolean { /** * Validates that a value is a number. * - * @param {any} value The value to validate. - * @return {boolean} Whether the value is a number or not. + * @param value The value to validate. + * @returns Whether the value is a number or not. */ export function isNumber(value: any): boolean { return typeof value === 'number' && !isNaN(value); @@ -73,8 +73,8 @@ export function isNumber(value: any): boolean { /** * Validates that a value is a string. * - * @param {any} value The value to validate. - * @return {boolean} Whether the value is a string or not. + * @param value The value to validate. + * @returns Whether the value is a string or not. */ export function isString(value: any): value is string { return typeof value === 'string'; @@ -84,8 +84,8 @@ export function isString(value: any): value is string { /** * Validates that a value is a base64 string. * - * @param {any} value The value to validate. - * @return {boolean} Whether the value is a base64 string or not. + * @param value The value to validate. + * @returns Whether the value is a base64 string or not. */ export function isBase64String(value: any): boolean { if (!isString(value)) { @@ -98,8 +98,8 @@ export function isBase64String(value: any): boolean { /** * Validates that a value is a non-empty string. * - * @param {any} value The value to validate. - * @return {boolean} Whether the value is a non-empty string or not. + * @param value The value to validate. + * @returns Whether the value is a non-empty string or not. */ export function isNonEmptyString(value: any): value is string { return isString(value) && value !== ''; @@ -109,8 +109,8 @@ export function isNonEmptyString(value: any): value is string { /** * Validates that a value is a nullable object. * - * @param {any} value The value to validate. - * @return {boolean} Whether the value is an object or not. + * @param value The value to validate. + * @returns Whether the value is an object or not. */ export function isObject(value: any): boolean { return typeof value === 'object' && !isArray(value); @@ -120,8 +120,8 @@ export function isObject(value: any): boolean { /** * Validates that a value is a non-null object. * - * @param {any} value The value to validate. - * @return {boolean} Whether the value is a non-null object or not. + * @param value The value to validate. + * @returns Whether the value is a non-null object or not. */ export function isNonNullObject(value: T | null | undefined): value is T { return isObject(value) && value !== null; @@ -131,8 +131,8 @@ export function isNonNullObject(value: T | null | undefined): value is T { /** * Validates that a string is a valid Firebase Auth uid. * - * @param {any} uid The string to validate. - * @return {boolean} Whether the string is a valid Firebase Auth uid. + * @param uid The string to validate. + * @returns Whether the string is a valid Firebase Auth uid. */ export function isUid(uid: any): boolean { return typeof uid === 'string' && uid.length > 0 && uid.length <= 128; @@ -142,8 +142,8 @@ export function isUid(uid: any): boolean { /** * Validates that a string is a valid Firebase Auth password. * - * @param {any} password The password string to validate. - * @return {boolean} Whether the string is a valid Firebase Auth password. + * @param password The password string to validate. + * @returns Whether the string is a valid Firebase Auth password. */ export function isPassword(password: any): boolean { // A password must be a string of at least 6 characters. @@ -154,8 +154,8 @@ export function isPassword(password: any): boolean { /** * Validates that a string is a valid email. * - * @param {any} email The string to validate. - * @return {boolean} Whether the string is valid email or not. + * @param email The string to validate. + * @returns Whether the string is valid email or not. */ export function isEmail(email: any): boolean { if (typeof email !== 'string') { @@ -170,8 +170,8 @@ export function isEmail(email: any): boolean { /** * Validates that a string is a valid phone number. * - * @param {any} phoneNumber The string to validate. - * @return {boolean} Whether the string is a valid phone number or not. + * @param phoneNumber The string to validate. + * @returns Whether the string is a valid phone number or not. */ export function isPhoneNumber(phoneNumber: any): boolean { if (typeof phoneNumber !== 'string') { @@ -190,7 +190,7 @@ export function isPhoneNumber(phoneNumber: any): boolean { * Validates that a string is a valid ISO date string. * * @param dateString The string to validate. - * @return Whether the string is a valid ISO date string. + * @returns Whether the string is a valid ISO date string. */ export function isISODateString(dateString: any): boolean { try { @@ -206,7 +206,7 @@ export function isISODateString(dateString: any): boolean { * Validates that a string is a valid UTC date string. * * @param dateString The string to validate. - * @return Whether the string is a valid UTC date string. + * @returns Whether the string is a valid UTC date string. */ export function isUTCDateString(dateString: any): boolean { try { @@ -221,8 +221,8 @@ export function isUTCDateString(dateString: any): boolean { /** * Validates that a string is a valid web URL. * - * @param {any} urlStr The string to validate. - * @return {boolean} Whether the string is valid web URL or not. + * @param urlStr The string to validate. + * @returns Whether the string is valid web URL or not. */ export function isURL(urlStr: any): boolean { if (typeof urlStr !== 'string') { @@ -267,8 +267,8 @@ export function isURL(urlStr: any): boolean { /** * Validates that the provided topic is a valid FCM topic name. * - * @param {any} topic The topic to validate. - * @return {boolean} Whether the provided topic is a valid FCM topic name. + * @param topic The topic to validate. + * @returns Whether the provided topic is a valid FCM topic name. */ export function isTopic(topic: any): boolean { if (typeof topic !== 'string') {