API docs

Author: DellaBitta

etc/firebase-admin.app.api.md

@@ -97,7 +97,7 @@ export interface GoogleOAuthAccessToken {
     expires_in: number;
 }
 
-// @public (undocumented)
+// @public
 export function initializeApp(options?: AppOptions, appName?: string): App;
 
 // @public

src/app/lifecycle.ts

@@ -46,7 +46,7 @@ export class AppStore {
       const currentApp = this.appStore.get(appName)!;
       if (currentApp.autoInit() !== autoInit) {
         throw new FirebaseAppError(
-          AppErrorCodes.INVALID_ARGUMENT,
+          AppErrorCodes.INVALID_APP_OPTIONS,
           `Firebase app named "${appName}" attempted mismatch between custom AppOptions` +
           ' and an App created via Auto Init.'
         )
@@ -172,6 +172,35 @@ function validateAppNameFormat(appName: string): void {
 
 export const defaultAppStore = new AppStore();
 
+/**
+ * Initializes the App instance.
+ *
+ * Creates a new instance of {@link App} if one doesn't exist, or returns an existing
+ * {@link App} instance if one exists with the same `appName` and `options`.
+ * 
+ * Note, due to the inablity to compare `http.Agent` objects and `Credential` objects,
+ * this function cannot support idempotency if either of `options.httpAgent` or
+ * `options.credential` are defined. When either is defined, subsequent invocations will 
+ * throw instead of returning an {@link App} object.
+ *
+ * @param options - Optional A set of {@link AppOptions} for the {@link App} instance.
+ *   If not present, `initializeApp` will try to initialize with the options from the
+ *   `FIREBASE_CONFIG` environment variable. If the environment variable contains a string
+ *   that starts with `{` it will be parsed as JSON, otherwise it will be assumed to be
+ *   pointing to a file.
+ * @param appName - Optional name of the FirebaseApp instance.
+ *
+ * @returns A new App instance, or the existing App if the instance already exists with
+ *   the provided configuration.
+ *
+ * @throws FirebaseAppError if an {@link App} with the same name has already been
+ *   initialized with a different set of AppOptions.
+ * @throws FirebaseAppError if an existing {@link App} exists and `options.httpAgent`
+ *   or `options.credential` are defined. This is due to the function's inability to
+ *   determine if the existing {@link App}'s `options` compare to the `options` parameter
+ *   of this function. It's recommended to use {@link getApp} or {@link getApps} if your
+ *   implementation uses either of these two fields in {@link AppOptions}.
+ */
 export function initializeApp(options?: AppOptions, appName: string = DEFAULT_APP_NAME): App {
   return defaultAppStore.initializeApp(options, appName);
 }