fix: Updated documentation for app and instance-id entry points (#1168)

hiranya911 · web-flow · commit 5a0f2fb88c52 · 2021-02-16T10:43:49.000-08:00
* fix: Added API ref docs to firebase-admin/app

* fix: Added API docs to firebase-admin/instance-id
diff --git a/etc/firebase-admin.api.md b/etc/firebase-admin.api.md
@@ -10,7 +10,7 @@ import { FirebaseDatabase } from '@firebase/database-types';
 import * as _firestore from '@google-cloud/firestore';
 import * as rtdb from '@firebase/database-types';
 
-// @public (undocumented)
+// @public
 export interface App {
     name: string;
     options: AppOptions;
@@ -46,7 +46,7 @@ export namespace app {
     }
 }
 
-// @public (undocumented)
+// @public
 export function applicationDefault(httpAgent?: Agent): Credential;
 
 // @public
@@ -274,10 +274,10 @@ export namespace auth {
     export type UserRecord = UserRecord;
 }
 
-// @public (undocumented)
+// @public
 export function cert(serviceAccountPathOrObject: string | ServiceAccount, httpAgent?: Agent): Credential;
 
-// @public (undocumented)
+// @public
 export interface Credential {
     getAccessToken(): Promise<GoogleOAuthAccessToken>;
 }
@@ -316,7 +316,7 @@ export namespace database {
     const ServerValue: rtdb.ServerValue;
 }
 
-// @public (undocumented)
+// @public
 export function deleteApp(app: App): Promise<void>;
 
 // @public
@@ -618,7 +618,7 @@ export namespace projectManagement {
     export type ShaCertificate = ShaCertificate;
 }
 
-// @public (undocumented)
+// @public
 export function refreshToken(refreshTokenPathOrObject: string | object, httpAgent?: Agent): Credential;
 
 // @public
diff --git a/etc/firebase-admin.app.api.md b/etc/firebase-admin.app.api.md
@@ -6,13 +6,13 @@
 
 import { Agent } from 'http';
 
-// @public (undocumented)
+// @public
 export interface App {
     name: string;
     options: AppOptions;
 }
 
-// @public (undocumented)
+// @public
 export function applicationDefault(httpAgent?: Agent): Credential;
 
 // @public
@@ -26,15 +26,15 @@ export interface AppOptions {
     storageBucket?: string;
 }
 
-// @public (undocumented)
+// @public
 export function cert(serviceAccountPathOrObject: string | ServiceAccount, httpAgent?: Agent): Credential;
 
-// @public (undocumented)
+// @public
 export interface Credential {
     getAccessToken(): Promise<GoogleOAuthAccessToken>;
 }
 
-// @public (undocumented)
+// @public
 export function deleteApp(app: App): Promise<void>;
 
 // @public
@@ -68,7 +68,7 @@ export interface GoogleOAuthAccessToken {
 // @public (undocumented)
 export function initializeApp(options?: AppOptions, name?: string): App;
 
-// @public (undocumented)
+// @public
 export function refreshToken(refreshTokenPathOrObject: string | object, httpAgent?: Agent): Credential;
 
 // @public (undocumented)
diff --git a/etc/firebase-admin.instance-id.api.md b/etc/firebase-admin.instance-id.api.md
@@ -8,7 +8,7 @@ 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 getInstanceId(app?: App): InstanceId;
 
 // @public
diff --git a/src/app/core.ts b/src/app/core.ts
@@ -84,6 +84,16 @@ export interface AppOptions {
   httpAgent?: Agent;
 }
 
+/**
+ * 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 {
 
   /**
@@ -94,14 +104,14 @@ export interface App {
    * @example
    * ```javascript
    * // The default app's name is "[DEFAULT]"
-   * admin.initializeApp(defaultAppConfig);
+   * initializeApp(defaultAppConfig);
    * console.log(admin.app().name);  // "[DEFAULT]"
    * ```
    *
    * @example
    * ```javascript
    * // A named app's name is what you provide to initializeApp()
-   * var otherApp = admin.initializeApp(otherAppConfig, "other");
+   * const otherApp = initializeApp(otherAppConfig, "other");
    * console.log(otherApp.name);  // "other"
    * ```
    */
@@ -116,7 +126,7 @@ export interface App {
    *
    * @example
    * ```javascript
-   * var app = admin.initializeApp(config);
+   * const app = initializeApp(config);
    * console.log(app.options.credential === config.credential);  // true
    * console.log(app.options.databaseURL === config.databaseURL);  // true
    * ```
diff --git a/src/app/credential-factory.ts b/src/app/credential-factory.ts
@@ -26,13 +26,92 @@ let globalAppDefaultCred: Credential | undefined;
 const globalCertCreds: { [key: string]: ServiceAccountCredential } = {};
 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}
+ * 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()`}.
+ *
+ * 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}
+ * for more details.
+ *
+ * @example
+ * ```javascript
+ * initializeApp({
+ *   credential: applicationDefault(),
+ *   databaseURL: "https://<DATABASE_NAME>.firebaseio.com"
+ * });
+ * ```
+ *
+ * @param httpAgent Optional [HTTP Agent](https://nodejs.org/api/http.html#http_class_http_agent)
+ *   to be used when retrieving access tokens from Google token servers.
+ *
+ * @return A credential authenticated via Google
+ *   Application Default Credentials that can be used to initialize an app.
+ */
 export function applicationDefault(httpAgent?: Agent): Credential {
   if (typeof globalAppDefaultCred === 'undefined') {
     globalAppDefaultCred = getApplicationDefault(httpAgent);
   }
   return globalAppDefaultCred;
 }
 
+/**
+ * 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()`}.
+ *
+ * See
+ * {@link
+ *   https://firebase.google.com/docs/admin/setup#initialize_the_sdk
+ *   Initialize the SDK}
+ * for more details.
+ *
+ * @example
+ * ```javascript
+ * // Providing a path to a service account key JSON file
+ * const serviceAccount = require("path/to/serviceAccountKey.json");
+ * initializeApp({
+ *   credential: cert(serviceAccount),
+ *   databaseURL: "https://<DATABASE_NAME>.firebaseio.com"
+ * });
+ * ```
+ *
+ * @example
+ * ```javascript
+ * // Providing a service account object inline
+ * initializeApp({
+ *   credential: cert({
+ *     projectId: "<PROJECT_ID>",
+ *     clientEmail: "foo@<PROJECT_ID>.iam.gserviceaccount.com",
+ *     privateKey: "-----BEGIN PRIVATE KEY-----<KEY>-----END PRIVATE KEY-----\n"
+ *   }),
+ *   databaseURL: "https://<DATABASE_NAME>.firebaseio.com"
+ * });
+ * ```
+ *
+ * @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)
+ *   to be used when retrieving access tokens from Google token servers.
+ *
+ * @return 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 {
   const stringifiedServiceAccount = JSON.stringify(serviceAccountPathOrObject);
   if (!(stringifiedServiceAccount in globalCertCreds)) {
@@ -42,6 +121,39 @@ export function cert(serviceAccountPathOrObject: string | ServiceAccount, httpAg
   return globalCertCreds[stringifiedServiceAccount];
 }
 
+/**
+ * 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()`}.
+ *
+ * See
+ * {@link
+ *   https://firebase.google.com/docs/admin/setup#initialize_the_sdk
+ *   Initialize the SDK}
+ * for more details.
+ *
+ * @example
+ * ```javascript
+ * // Providing a path to a refresh token JSON file
+ * const refreshToken = require("path/to/refreshToken.json");
+ * initializeApp({
+ *   credential: refreshToken(refreshToken),
+ *   databaseURL: "https://<DATABASE_NAME>.firebaseio.com"
+ * });
+ * ```
+ *
+ * @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)
+ *   to be used when retrieving access tokens from Google token servers.
+ *
+ * @return 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 {
   const stringifiedRefreshToken = JSON.stringify(refreshTokenPathOrObject);
   if (!(stringifiedRefreshToken in globalRefreshTokenCreds)) {
diff --git a/src/app/credential.ts b/src/app/credential.ts
@@ -29,6 +29,14 @@ export interface GoogleOAuthAccessToken {
   expires_in: number;
 }
 
+/**
+ * Interface that provides Google OAuth2 access tokens used to authenticate
+ * with Firebase services.
+ *
+ * In most cases, you will not need to implement this yourself and can instead
+ * use the default implementations provided by
+ * {@link credential `admin.credential`}.
+ */
 export interface Credential {
   /**
    * Returns a Google OAuth2 access token object used to authenticate with
diff --git a/src/app/lifecycle.ts b/src/app/lifecycle.ts
@@ -41,6 +41,23 @@ export function getApps(): App[] {
   return defaultNamespace.apps;
 }
 
+/**
+ * Renders this given `App` unusable and frees the resources of
+ * all associated services (though it does *not* clean up any backend
+ * resources). When running the SDK locally, this method
+ * must be called to ensure graceful termination of the process.
+ *
+ * @example
+ * ```javascript
+ * deleteApp(app)
+ *   .then(function() {
+ *     console.log("App deleted successfully");
+ *   })
+ *   .catch(function(error) {
+ *     console.log("Error deleting app:", error);
+ *   });
+ * ```
+ */
 export function deleteApp(app: App): Promise<void> {
   if (typeof app !== 'object' || app === null || !('options' in app)) {
     throw new FirebaseAppError(AppErrorCodes.INVALID_ARGUMENT, 'Invalid app argument.');
diff --git a/src/instance-id/index.ts b/src/instance-id/index.ts
@@ -20,6 +20,36 @@ import { InstanceId } from './instance-id';
 
 export { InstanceId };
 
+/**
+ * Gets the {@link InstanceId `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.
+ *
+ * @example
+ * ```javascript
+ * // Get the Instance ID service for the default app
+ * const defaultInstanceId = getInstanceId();
+ * ```
+ *
+ * @example
+ * ```javascript
+ * // Get the Instance ID service for a given app
+ * const otherInstanceId = getInstanceId(otherApp);
+ *```
+ *
+ * @param app Optional app whose `InstanceId` service to
+ *   return. If not provided, the default `InstanceId` service will be
+ *   returned.
+ *
+ * @return The default `InstanceId` service if
+ *   no app is provided or the `InstanceId` service associated with the
+ *   provided app.
+ */
 export function getInstanceId(app?: App): InstanceId {
   if (typeof app === 'undefined') {
     app = getApp();
diff --git a/src/instance-id/instance-id.ts b/src/instance-id/instance-id.ts
@@ -20,18 +20,8 @@ import { FirebaseInstanceIdRequestHandler } from './instance-id-request-internal
 import * as validator from '../utils/validator';
 
 /**
- * Gets the {@link InstanceId `InstanceId`} service for the
- * current app.
- *
- * @example
- * ```javascript
- * var instanceId = app.instanceId();
- * // The above is shorthand for:
- * // var instanceId = admin.instanceId(app);
- * ```
- *
- * @return The `InstanceId` service for the
- *   current app.
+ * The `InstanceId` service enables deleting the Firebase instance IDs
+ * associated with Firebase client app instances.
  */
 export class InstanceId {
 
