diff --git a/etc/firebase-admin.database.api.md b/etc/firebase-admin.database.api.md index 0b8c5b0790..3b9fe43324 100644 --- a/etc/firebase-admin.database.api.md +++ b/etc/firebase-admin.database.api.md @@ -49,15 +49,15 @@ export namespace database { export { DataSnapshot } -// @public (undocumented) +// @public export const enableLogging: typeof rtdb.enableLogging; export { EventType } -// @public (undocumented) +// @public export function getDatabase(app?: App): Database; -// @public (undocumented) +// @public export function getDatabaseWithUrl(url: string, app?: App): Database; export { OnDisconnect } @@ -66,7 +66,7 @@ export { Query } export { Reference } -// @public (undocumented) +// @public export const ServerValue: rtdb.ServerValue; export { ThenableReference } diff --git a/etc/firebase-admin.machine-learning.api.md b/etc/firebase-admin.machine-learning.api.md index 9f1204e7e2..2560737b4a 100644 --- a/etc/firebase-admin.machine-learning.api.md +++ b/etc/firebase-admin.machine-learning.api.md @@ -24,7 +24,7 @@ export interface GcsTfliteModelOptions extends ModelOptionsBase { // Warning: (ae-forgotten-export) The symbol "App" needs to be exported by the entry point index.d.ts // -// @public (undocumented) +// @public export function getMachineLearning(app?: App): MachineLearning; // @public @@ -79,30 +79,19 @@ export namespace machineLearning { // @public export class Model { - // (undocumented) get createTime(): string; - // (undocumented) get displayName(): string; - // (undocumented) get etag(): string; get locked(): boolean; - // (undocumented) get modelHash(): string | undefined; - // (undocumented) get modelId(): string; - // (undocumented) get published(): boolean; - // (undocumented) get tags(): string[]; - // (undocumented) get tfliteModel(): TFLiteModel | undefined; - // (undocumented) toJSON(): { [key: string]: any; }; - // (undocumented) get updateTime(): string; - // (undocumented) get validationError(): string | undefined; waitForUnlocked(maxTimeMillis?: number): Promise; } diff --git a/etc/firebase-admin.messaging.api.md b/etc/firebase-admin.messaging.api.md index 07eb7c9cab..eec7b21f45 100644 --- a/etc/firebase-admin.messaging.api.md +++ b/etc/firebase-admin.messaging.api.md @@ -165,7 +165,7 @@ export interface FcmOptions { // Warning: (ae-forgotten-export) The symbol "App" needs to be exported by the entry point index.d.ts // -// @public (undocumented) +// @public export function getMessaging(app?: App): Messaging; // @public diff --git a/etc/firebase-admin.project-management.api.md b/etc/firebase-admin.project-management.api.md index f8d3ebcf34..eb166be66c 100644 --- a/etc/firebase-admin.project-management.api.md +++ b/etc/firebase-admin.project-management.api.md @@ -6,7 +6,7 @@ import { Agent } from 'http'; -// @public (undocumented) +// @public export class AndroidApp { addShaCertificate(certificateToAdd: ShaCertificate): Promise; // (undocumented) @@ -43,10 +43,10 @@ export enum AppPlatform { // Warning: (ae-forgotten-export) The symbol "App" needs to be exported by the entry point index.d.ts // -// @public (undocumented) +// @public export function getProjectManagement(app?: App): ProjectManagement; -// @public (undocumented) +// @public export class IosApp { // (undocumented) readonly appId: string; diff --git a/etc/firebase-admin.remote-config.api.md b/etc/firebase-admin.remote-config.api.md index eee1507fba..063c2b4167 100644 --- a/etc/firebase-admin.remote-config.api.md +++ b/etc/firebase-admin.remote-config.api.md @@ -13,7 +13,7 @@ export interface ExplicitParameterValue { // Warning: (ae-forgotten-export) The symbol "App" needs to be exported by the entry point index.d.ts // -// @public (undocumented) +// @public export function getRemoteConfig(app?: App): RemoteConfig; // @public diff --git a/etc/firebase-admin.security-rules.api.md b/etc/firebase-admin.security-rules.api.md index 81310c26c3..bef96e2edf 100644 --- a/etc/firebase-admin.security-rules.api.md +++ b/etc/firebase-admin.security-rules.api.md @@ -8,14 +8,12 @@ import { Agent } from 'http'; // Warning: (ae-forgotten-export) The symbol "App" needs to be exported by the entry point index.d.ts // -// @public (undocumented) +// @public export function getSecurityRules(app?: App): SecurityRules; // @public -export class Ruleset { - // (undocumented) +export class Ruleset implements RulesetMetadata { readonly createTime: string; - // (undocumented) readonly name: string; // (undocumented) readonly source: RulesFile[]; @@ -27,11 +25,9 @@ export interface RulesetMetadata { readonly name: string; } -// @public (undocumented) +// @public export class RulesetMetadataList { - // (undocumented) readonly nextPageToken?: string; - // (undocumented) readonly rulesets: RulesetMetadata[]; } diff --git a/etc/firebase-admin.storage.api.md b/etc/firebase-admin.storage.api.md index d13887d9df..f5049af101 100644 --- a/etc/firebase-admin.storage.api.md +++ b/etc/firebase-admin.storage.api.md @@ -9,13 +9,12 @@ import { Bucket } from '@google-cloud/storage'; // Warning: (ae-forgotten-export) The symbol "App" needs to be exported by the entry point index.d.ts // -// @public (undocumented) +// @public export function getStorage(app?: App): Storage; // @public export class Storage { get app(): App; - // (undocumented) bucket(name?: string): Bucket; } diff --git a/src/database/index.ts b/src/database/index.ts index 4bc350ee05..4cc274cf49 100644 --- a/src/database/index.ts +++ b/src/database/index.ts @@ -35,13 +35,78 @@ export { ThenableReference, } from '@firebase/database-types'; +/** + * [`enableLogging`](https://firebase.google.com/docs/reference/js/firebase.database#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) + * module from the `@firebase/database` package. + */ export const ServerValue: rtdb.ServerValue = serverValueConst; +/** + * Gets the {@link database.Database `Database`} service for the default + * app or a given app. + * + * `getDatabase()` can be called with no arguments to access the default + * app's {@link database.Database `Database`} service or as + * `getDatabase(app)` to access the + * {@link database.Database `Database`} service associated with a specific + * app. + * + * @example + * ```javascript + * // Get the Database service for the default app + * const defaultDatabase = getDatabase(); + * ``` + * + * @example + * ```javascript + * // Get the Database service for a specific app + * const otherDatabase = getDatabase(app); + * ``` + * + * @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 + * is provided or the `Database` service associated with the provided app. + */ export function getDatabase(app?: App): Database { return getDatabaseInstance({ app }); } +/** + * Gets the {@link database.Database `Database`} service for the default + * app or a given app. + * + * `getDatabaseWithUrl()` can be called with no arguments to access the default + * app's {@link database.Database `Database`} service or as + * `getDatabaseWithUrl(app)` to access the + * {@link database.Database `Database`} service associated with a specific + * app. + * + * @example + * ```javascript + * // Get the Database service for the default app + * const defaultDatabase = getDatabaseWithUrl('https://example.firebaseio.com'); + * ``` + * + * @example + * ```javascript + * // Get the Database service for a specific app + * const otherDatabase = getDatabaseWithUrl('https://example.firebaseio.com', app); + * ``` + * + * @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 + * is provided or the `Database` service associated with the provided app. + */ export function getDatabaseWithUrl(url: string, app?: App): Database { return getDatabaseInstance({ url, app }); } diff --git a/src/machine-learning/index.ts b/src/machine-learning/index.ts index c12da2b832..e3cdf83d65 100644 --- a/src/machine-learning/index.ts +++ b/src/machine-learning/index.ts @@ -32,6 +32,35 @@ export { ModelOptionsBase, } from './machine-learning-api-client'; +/** + * Gets the {@link machineLearning.MachineLearning `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. + */ export function getMachineLearning(app?: App): MachineLearning { if (typeof app === 'undefined') { app = getApp(); diff --git a/src/machine-learning/machine-learning.ts b/src/machine-learning/machine-learning.ts index c150c89e61..5c60438adf 100644 --- a/src/machine-learning/machine-learning.ts +++ b/src/machine-learning/machine-learning.ts @@ -58,7 +58,7 @@ export interface TFLiteModel { } /** - * The Firebase Machine Learning class + * The Firebase `MachineLearning` service interface. */ export class MachineLearning { @@ -84,20 +84,19 @@ export class MachineLearning { } /** - * Returns the app associated with this ML instance. - * - * @return The app associated with this ML instance. + * The {@link app.App} associated with the current `MachineLearning` + * service instance. */ public get app(): App { return this.appInternal; } /** - * Creates a model in Firebase ML. + * Creates a model in the current Firebase project. * - * @param {ModelOptions} model The model to create. + * @param model The model to create. * - * @return {Promise} A Promise fulfilled with the created model. + * @return A Promise fulfilled with the created model. */ public createModel(model: ModelOptions): Promise { return this.signUrlIfPresent(model) @@ -107,12 +106,12 @@ export class MachineLearning { } /** - * Updates a model in Firebase ML. + * Updates a model's metadata or model file. * - * @param {string} modelId The id of the model to update. - * @param {ModelOptions} model The model fields to update. + * @param modelId The ID of the model to update. + * @param model The model fields to update. * - * @return {Promise} A Promise fulfilled with the updated model. + * @return A Promise fulfilled with the updated model. */ public updateModel(modelId: string, model: ModelOptions): Promise { const updateMask = utils.generateUpdateMask(model); @@ -123,33 +122,35 @@ export class MachineLearning { } /** - * Publishes a model in Firebase ML. + * Publishes a Firebase ML model. + * + * A published model can be downloaded to client apps. * - * @param {string} modelId The id of the model to publish. + * @param modelId The ID of the model to publish. * - * @return {Promise} A Promise fulfilled with the published model. + * @return A Promise fulfilled with the published model. */ public publishModel(modelId: string): Promise { return this.setPublishStatus(modelId, true); } /** - * Unpublishes a model in Firebase ML. + * Unpublishes a Firebase ML model. * - * @param {string} modelId The id of the model to unpublish. + * @param modelId The ID of the model to unpublish. * - * @return {Promise} A Promise fulfilled with the unpublished model. + * @return A Promise fulfilled with the unpublished model. */ public unpublishModel(modelId: string): Promise { return this.setPublishStatus(modelId, false); } /** - * Gets a model from Firebase ML. + * Gets the model specified by the given ID. * - * @param {string} modelId The id of the model to get. + * @param modelId The ID of the model to get. * - * @return {Promise} A Promise fulfilled with the unpublished model. + * @return A Promise fulfilled with the model object. */ public getModel(modelId: string): Promise { return this.client.getModel(modelId) @@ -157,14 +158,14 @@ export class MachineLearning { } /** - * Lists models from Firebase ML. + * Lists the current project's models. * - * @param {ListModelsOptions} options The listing options. + * @param options The listing options. * - * @return {Promise<{models: Model[], pageToken?: string}>} A promise that + * @return 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. + * token. For the last page, an empty list of models and no page token + * are returned. */ public listModels(options: ListModelsOptions = {}): Promise { return this.client.listModels(options) @@ -187,9 +188,9 @@ export class MachineLearning { } /** - * Deletes a model from Firebase ML. + * Deletes a model from the current project. * - * @param {string} modelId The id of the model to delete. + * @param modelId The ID of the model to delete. */ public deleteModel(modelId: string): Promise { return this.client.deleteModel(modelId); @@ -257,55 +258,80 @@ export class Model { this.client = client; } + /** The ID of the model. */ get modelId(): string { return extractModelId(this.model.name); } + /** + * The model's name. This is the name you use from your app to load the + * model. + */ get displayName(): string { return this.model.displayName!; } + /** + * The model's tags, which can be used to group or filter models in list + * operations. + */ get tags(): string[] { return this.model.tags || []; } + /** The timestamp of the model's creation. */ get createTime(): string { return new Date(this.model.createTime).toUTCString(); } + /** The timestamp of the model's most recent update. */ get updateTime(): string { return new Date(this.model.updateTime).toUTCString(); } + /** Error message when model validation fails. */ get validationError(): string | undefined { return this.model.state?.validationError?.message; } + /** True if the model is published. */ get published(): boolean { return this.model.state?.published || false; } + /** + * The ETag identifier of the current version of the model. This value + * changes whenever you update any of the model's properties. + */ get etag(): string { return this.model.etag; } + /** + * The hash of the model's `tflite` file. This value changes only when + * you upload a new TensorFlow Lite model. + */ get modelHash(): string | undefined { return this.model.modelHash; } + /** Metadata about the model's TensorFlow Lite model file. */ get tfliteModel(): TFLiteModel | undefined { // Make a copy so people can't directly modify the private this.model object. return deepCopy(this.model.tfliteModel); } /** - * Locked indicates if there are active long running operations on the model. - * Models may not be modified when they are locked. + * True if the model is locked by a server-side operation. You can't make + * changes to a locked model. See {@link waitForUnlocked `waitForUnlocked()`}. */ public get locked(): boolean { return (this.model.activeOperations?.length ?? 0) > 0; } + /** + * Return the model as a JSON object. + */ public toJSON(): {[key: string]: any} { // We can't just return this.model because it has extra fields and // different formats etc. So we build the expected model object. @@ -338,9 +364,13 @@ export class Model { } /** - * Wait for the active operations on the model to complete. - * @param maxTimeMillis The number of milliseconds to wait for the model to be unlocked. If unspecified, - * a default will be used. + * Wait for the model to be unlocked. + * + * @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 + * or the maximum wait time has passed. */ public waitForUnlocked(maxTimeMillis?: number): Promise { if ((this.model.activeOperations?.length ?? 0) > 0) { diff --git a/src/messaging/index.ts b/src/messaging/index.ts index 9c8634cba8..5d799cf6b0 100644 --- a/src/messaging/index.ts +++ b/src/messaging/index.ts @@ -60,6 +60,35 @@ export { NotificationMessagePayload, } from './messaging-api'; +/** + * Gets the {@link messaging.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. + * + * @example + * ```javascript + * // Get the Messaging service for the default app + * const defaultMessaging = getMessaging(); + * ``` + * + * @example + * ```javascript + * // Get the Messaging service for a given app + * const otherMessaging = getMessaging(otherApp); + * ``` + * + * @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 + * app is provided or the `Messaging` service associated with the provided + * app. + */ export function getMessaging(app?: App): Messaging { if (typeof app === 'undefined') { app = getApp(); diff --git a/src/messaging/messaging.ts b/src/messaging/messaging.ts index 0c37ee30c5..b1803a513e 100644 --- a/src/messaging/messaging.ts +++ b/src/messaging/messaging.ts @@ -221,9 +221,13 @@ export class Messaging { } /** - * Returns the app associated with this Messaging instance. + * The {@link app.App app} associated with the current `Messaging` service + * instance. * - * @return The app associated with this Messaging instance. + * @example + * ```javascript + * var app = messaging.app; + * ``` */ get app(): App { return this.appInternal; diff --git a/src/project-management/android-app.ts b/src/project-management/android-app.ts index 808c25c7e4..5756051c28 100644 --- a/src/project-management/android-app.ts +++ b/src/project-management/android-app.ts @@ -39,7 +39,14 @@ export interface AndroidAppMetadata extends AppMetadata { packageName: string; } +/** + * A reference to a Firebase Android app. + * + * Do not call this constructor directly. Instead, use + * [`projectManagement.androidApp()`](projectManagement.ProjectManagement#androidApp). + */ export class AndroidApp { + private readonly resourceName: string; /** diff --git a/src/project-management/index.ts b/src/project-management/index.ts index 26e7f7aa5e..35cbe3b4c1 100644 --- a/src/project-management/index.ts +++ b/src/project-management/index.ts @@ -23,6 +23,34 @@ export { ProjectManagement } from './project-management'; 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. + * + * `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. + * + * @example + * ```javascript + * // Get the ProjectManagement service for the default app + * const defaultProjectManagement = getProjectManagement(); + * ``` + * + * @example + * ```javascript + * // Get the ProjectManagement service for a given app + * const otherProjectManagement = getProjectManagement(otherApp); + * ``` + * + * @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 + * `ProjectManagement` service associated with the provided app. + */ export function getProjectManagement(app?: App): ProjectManagement { if (typeof app === 'undefined') { app = getApp(); diff --git a/src/project-management/ios-app.ts b/src/project-management/ios-app.ts index 9d01ce23c6..0becebbb02 100644 --- a/src/project-management/ios-app.ts +++ b/src/project-management/ios-app.ts @@ -36,7 +36,14 @@ export interface IosAppMetadata extends AppMetadata { bundleId: string; } +/** + * A reference to a Firebase iOS app. + * + * Do not call this constructor directly. Instead, use + * [`projectManagement.iosApp()`](projectManagement.ProjectManagement#iosApp). + */ export class IosApp { + private readonly resourceName: string; /** @@ -56,7 +63,7 @@ export class IosApp { /** * Retrieves metadata about this iOS app. * - * @return {!Promise} A promise that + * @return A promise that * resolves to the retrieved metadata about this iOS app. */ public getMetadata(): Promise { diff --git a/src/remote-config/index.ts b/src/remote-config/index.ts index b7fd3fc15e..e97803c68f 100644 --- a/src/remote-config/index.ts +++ b/src/remote-config/index.ts @@ -34,6 +34,35 @@ export { } from './remote-config-api'; export { RemoteConfig } from './remote-config'; +/** + * Gets the {@link remoteConfig.RemoteConfig `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. + * + * @example + * ```javascript + * // Get the `RemoteConfig` service for the default app + * const defaultRemoteConfig = getRemoteConfig(); + * ``` + * + * @example + * ```javascript + * // Get the `RemoteConfig` service for a given app + * const otherRemoteConfig = getRemoteConfig(otherApp); + * ``` + * + * @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 + * app is provided, or the `RemoteConfig` service associated with the provided + * app. + */ export function getRemoteConfig(app?: App): RemoteConfig { if (typeof app === 'undefined') { app = getApp(); diff --git a/src/remote-config/remote-config.ts b/src/remote-config/remote-config.ts index 5f2ce6b252..c6b23517ef 100644 --- a/src/remote-config/remote-config.ts +++ b/src/remote-config/remote-config.ts @@ -29,7 +29,7 @@ import { } from './remote-config-api'; /** - * Remote Config service bound to the provided app. + * The Firebase `RemoteConfig` service interface. */ export class RemoteConfig { @@ -234,16 +234,16 @@ class RemoteConfigTemplateImpl implements RemoteConfigTemplate { /** * Gets the ETag of the template. * - * @return {string} The ETag of the Remote Config template. + * @return The ETag of the Remote Config template. */ get etag(): string { return this.etagInternal; } /** - * @return {RemoteConfigTemplate} A JSON-serializable representation of this object. + * @return A JSON-serializable representation of this object. */ - public toJSON(): RemoteConfigTemplate { + public toJSON(): object { return { conditions: this.conditions, parameters: this.parameters, @@ -359,9 +359,9 @@ class VersionImpl implements Version { } /** - * @return {Version} A JSON-serializable representation of this object. + * @return A JSON-serializable representation of this object. */ - public toJSON(): Version { + public toJSON(): object { return { versionNumber: this.versionNumber, updateOrigin: this.updateOrigin, diff --git a/src/security-rules/index.ts b/src/security-rules/index.ts index 0af1ef8feb..72582520d9 100644 --- a/src/security-rules/index.ts +++ b/src/security-rules/index.ts @@ -34,6 +34,34 @@ import { SecurityRules as TSecurityRules, } from './security-rules'; +/** + * Gets the {@link securityRules.SecurityRules + * `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. + * + * @example + * ```javascript + * // Get the SecurityRules service for the default app + * const defaultSecurityRules = getSecurityRules(); + * ``` + * + * @example + * ```javascript + * // Get the SecurityRules service for a given app + * const otherSecurityRules = getSecurityRules(otherApp); + * ``` + * + * @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 + * `SecurityRules` service associated with the provided app. + */ export function getSecurityRules(app?: App): SecurityRules { if (typeof app === 'undefined') { app = getApp(); diff --git a/src/security-rules/security-rules.ts b/src/security-rules/security-rules.ts index bf18627a08..83c49b9e86 100644 --- a/src/security-rules/security-rules.ts +++ b/src/security-rules/security-rules.ts @@ -48,9 +48,19 @@ export interface RulesetMetadata { readonly createTime: string; } +/** + * A page of ruleset metadata. + */ export class RulesetMetadataList { + /** + * A batch of ruleset metadata. + */ public readonly rulesets: RulesetMetadata[]; + + /** + * The next page token if available. This is needed to retrieve the next batch. + */ public readonly nextPageToken?: string; /** @@ -77,12 +87,20 @@ export class RulesetMetadataList { } /** - * Represents a set of Firebase security rules. + * A set of Firebase security rules. */ -export class Ruleset { +export class Ruleset implements RulesetMetadata { + /** + * {@inheritdoc RulesetMetadata.name} + */ public readonly name: string; + + /** + * {@inheritdoc RulesetMetadata.createTime} + */ public readonly createTime: string; + public readonly source: RulesFile[]; /** @@ -106,9 +124,6 @@ export class Ruleset { /** * The Firebase `SecurityRules` service interface. - * - * Do not call this constructor directly. Instead, use - * [`admin.securityRules()`](securityRules#securityRules). */ export class SecurityRules { @@ -127,12 +142,14 @@ export class SecurityRules { } /** - * Gets the 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. + * Gets the {@link securityRules.Ruleset `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 {string} name Name of the Ruleset to retrieve. - * @returns {Promise} A promise that fulfills with the specified Ruleset. + * @param name Name of the `Ruleset` to retrieve. + * @return A promise that fulfills with the specified `Ruleset`. */ public getRuleset(name: string): Promise { return this.client.getRuleset(name) @@ -142,20 +159,22 @@ export class SecurityRules { } /** - * Gets the Ruleset currently applied to Cloud Firestore. Rejects with a `not-found` error if no Ruleset is - * applied on Firestore. + * Gets the {@link securityRules.Ruleset `Ruleset`} currently applied to + * Cloud Firestore. Rejects with a `not-found` error if no ruleset is applied + * on Firestore. * - * @returns {Promise} A promise that fulfills with the Firestore Ruleset. + * @return A promise that fulfills with the Firestore ruleset. */ public getFirestoreRuleset(): Promise { return this.getRulesetForRelease(SecurityRules.CLOUD_FIRESTORE); } /** - * Creates a new ruleset from the given source, and applies it to Cloud Firestore. + * Creates a new {@link securityRules.Ruleset `Ruleset`} from the given + * source, and applies it to Cloud Firestore. * - * @param {string|Buffer} source Rules source to apply. - * @returns {Promise} A promise that fulfills when the ruleset is created and released. + * @param source Rules source to apply. + * @return A promise that fulfills when the ruleset is created and released. */ public releaseFirestoreRulesetFromSource(source: string | Buffer): Promise { return Promise.resolve() @@ -172,23 +191,26 @@ export class SecurityRules { } /** - * Makes the specified ruleset the currently applied ruleset for Cloud Firestore. + * Applies the specified {@link securityRules.Ruleset `Ruleset`} ruleset + * to Cloud Firestore. * - * @param {string|RulesetMetadata} ruleset Name of the ruleset to apply or a RulesetMetadata object containing - * the name. - * @returns {Promise} A promise that fulfills when the ruleset is released. + * @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. */ public releaseFirestoreRuleset(ruleset: string | RulesetMetadata): Promise { return this.releaseRuleset(ruleset, SecurityRules.CLOUD_FIRESTORE); } /** - * Gets the Ruleset currently applied to a Cloud Storage bucket. Rejects with a `not-found` error if no Ruleset is - * applied on the bucket. + * Gets the {@link securityRules.Ruleset `Ruleset`} currently applied to a + * Cloud Storage bucket. Rejects with a `not-found` error if no ruleset is applied + * on the bucket. * - * @param {string=} 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`. - * @returns {Promise} A promise that fulfills with the Cloud Storage Ruleset. + * @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. */ public getStorageRuleset(bucket?: string): Promise { return Promise.resolve() @@ -201,12 +223,14 @@ export class SecurityRules { } /** - * Creates a new ruleset from the given source, and applies it to a Cloud Storage bucket. + * Creates a new {@link securityRules.Ruleset `Ruleset`} from the given + * source, and applies it to a Cloud Storage bucket. * - * @param {string|Buffer} source Rules source to apply. - * @param {string=} 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 `AppOptions`. - * @returns {Promise} A promise that fulfills when the ruleset is created and released. + * @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. */ public releaseStorageRulesetFromSource(source: string | Buffer, bucket?: string): Promise { return Promise.resolve() @@ -226,13 +250,15 @@ export class SecurityRules { } /** - * Makes the specified ruleset the currently applied ruleset for a Cloud Storage bucket. + * Applies the specified {@link securityRules.Ruleset `Ruleset`} ruleset + * to a Cloud Storage bucket. * - * @param {string|RulesetMetadata} ruleset Name of the ruleset to apply or a RulesetMetadata object containing - * the name. - * @param {string=} 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 `AppOptions`. - * @returns {Promise} A promise that fulfills when the ruleset is released. + * @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. */ public releaseStorageRuleset(ruleset: string | RulesetMetadata, bucket?: string): Promise { return Promise.resolve() diff --git a/src/storage/index.ts b/src/storage/index.ts index 3cc1e82c12..7310c1cf00 100644 --- a/src/storage/index.ts +++ b/src/storage/index.ts @@ -20,6 +20,28 @@ import { Storage } from './storage'; export { Storage } from './storage'; +/** + * Gets the {@link storage.Storage `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. + * + * @example + * ```javascript + * // Get the Storage service for the default app + * const defaultStorage = getStorage(); + * ``` + * + * @example + * ```javascript + * // Get the Storage service for a given app + * const otherStorage = getStorage(otherApp); + * ``` + */ export function getStorage(app?: App): Storage { if (typeof app === 'undefined') { app = getApp(); diff --git a/src/storage/storage.ts b/src/storage/storage.ts index d3511dc052..143ea25575 100644 --- a/src/storage/storage.ts +++ b/src/storage/storage.ts @@ -84,6 +84,8 @@ export class Storage { } /** + * Gets a reference to a Cloud Storage bucket. + * * @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) @@ -104,7 +106,8 @@ export class Storage { } /** - * @return The app associated with this Storage instance. + * Optional app whose `Storage` service to + * return. If not provided, the default `Storage` service will be returned. */ get app(): App { return this.appInternal;