From 9df03c97c31521c29f12a9a3ff2a1d9db625725a Mon Sep 17 00:00:00 2001
From: Feiyang <feiyangc@google.com>
Date: Fri, 9 Apr 2021 13:50:32 -0700
Subject: [PATCH] Update comments for installations, performance and remote
 config (#4766)

* add package descriptions

* initial capitals and periods

* add parameter description to installations

* add interface descriptions for perf

* address comments

* address comments2
---
 packages-exp/analytics-exp/src/index.ts       |  6 +++
 packages-exp/auth-exp/index.ts                |  6 +++
 packages-exp/functions-exp/src/index.ts       |  6 +++
 .../src/api/delete-installations.ts           |  1 +
 .../installations-exp/src/api/get-id.ts       |  1 +
 .../src/api/get-installations.ts              |  1 +
 .../installations-exp/src/api/get-token.ts    |  2 +
 .../installations-exp/src/api/on-id-change.ts |  3 ++
 packages-exp/installations-exp/src/index.ts   |  6 +++
 packages-exp/messaging-exp/src/index.ts       |  6 +++
 packages-exp/performance-exp/src/index.ts     | 16 +++++--
 .../performance-exp/src/public_types.ts       |  6 +++
 packages-exp/remote-config-exp/src/api.ts     | 46 +++++++++----------
 packages-exp/remote-config-exp/src/api2.ts    |  2 +-
 packages-exp/remote-config-exp/src/index.ts   |  6 +++
 packages/database/api-extractor.json          |  2 +-
 packages/database/exp/index.ts                |  6 +++
 packages/firestore/exp/index.ts               |  6 +++
 packages/storage/exp/index.ts                 |  6 +++
 scripts/exp/docgen.ts                         |  9 ++++
 20 files changed, 113 insertions(+), 30 deletions(-)

diff --git a/packages-exp/analytics-exp/src/index.ts b/packages-exp/analytics-exp/src/index.ts
index 34e91533ac4..0ec40773f81 100644
--- a/packages-exp/analytics-exp/src/index.ts
+++ b/packages-exp/analytics-exp/src/index.ts
@@ -1,3 +1,9 @@
+/**
+ * Firebase Analytics
+ *
+ * @packageDocumentation
+ */
+
 /**
  * @license
  * Copyright 2019 Google LLC
diff --git a/packages-exp/auth-exp/index.ts b/packages-exp/auth-exp/index.ts
index 2f985384abd..62f8204f643 100644
--- a/packages-exp/auth-exp/index.ts
+++ b/packages-exp/auth-exp/index.ts
@@ -1,3 +1,9 @@
+/**
+ * Firebase Authentication
+ *
+ * @packageDocumentation
+ */
+
 /**
  * @license
  * Copyright 2017 Google LLC
diff --git a/packages-exp/functions-exp/src/index.ts b/packages-exp/functions-exp/src/index.ts
index ad8b299b634..903974e84a2 100644
--- a/packages-exp/functions-exp/src/index.ts
+++ b/packages-exp/functions-exp/src/index.ts
@@ -1,3 +1,9 @@
+/**
+ * Cloud Functions for Firebase
+ *
+ * @packageDocumentation
+ */
+
 /**
  * @license
  * Copyright 2017 Google LLC
diff --git a/packages-exp/installations-exp/src/api/delete-installations.ts b/packages-exp/installations-exp/src/api/delete-installations.ts
index 6d4f8a007fd..e41163939b1 100644
--- a/packages-exp/installations-exp/src/api/delete-installations.ts
+++ b/packages-exp/installations-exp/src/api/delete-installations.ts
@@ -24,6 +24,7 @@ import { FirebaseInstallations } from '../interfaces/public-types';
 
 /**
  * Deletes the Firebase Installation and all associated data.
+ * @param installations - The `Installations` instance.
  *
  * @public
  */
diff --git a/packages-exp/installations-exp/src/api/get-id.ts b/packages-exp/installations-exp/src/api/get-id.ts
index ed2f50f5a59..cc3550fa1c5 100644
--- a/packages-exp/installations-exp/src/api/get-id.ts
+++ b/packages-exp/installations-exp/src/api/get-id.ts
@@ -23,6 +23,7 @@ import { FirebaseInstallations } from '../interfaces/public-types';
 /**
  * Creates a Firebase Installation if there isn't one for the app and
  * returns the Installation ID.
+ * @param installations - The `Installations` instance.
  *
  * @public
  */
diff --git a/packages-exp/installations-exp/src/api/get-installations.ts b/packages-exp/installations-exp/src/api/get-installations.ts
index b36ef6f3a94..529bea79ecf 100644
--- a/packages-exp/installations-exp/src/api/get-installations.ts
+++ b/packages-exp/installations-exp/src/api/get-installations.ts
@@ -20,6 +20,7 @@ import { FirebaseInstallations } from '../interfaces/public-types';
 
 /**
  * Returns an instance of FirebaseInstallations associated with the given FirebaseApp instance.
+ * @param app - The `FirebaseApp` instance.
  *
  * @public
  */
diff --git a/packages-exp/installations-exp/src/api/get-token.ts b/packages-exp/installations-exp/src/api/get-token.ts
index 664d50513c5..248ab68c7ec 100644
--- a/packages-exp/installations-exp/src/api/get-token.ts
+++ b/packages-exp/installations-exp/src/api/get-token.ts
@@ -25,6 +25,8 @@ import { FirebaseInstallations } from '../interfaces/public-types';
 
 /**
  * Returns an Installation auth token, identifying the current Firebase Installation.
+ * @param installations - The `Installations` instance.
+ * @param forceRefresh - Force refresh regardless of token expiration.
  *
  * @public
  */
diff --git a/packages-exp/installations-exp/src/api/on-id-change.ts b/packages-exp/installations-exp/src/api/on-id-change.ts
index 420cfb22fa1..4d0750f61b1 100644
--- a/packages-exp/installations-exp/src/api/on-id-change.ts
+++ b/packages-exp/installations-exp/src/api/on-id-change.ts
@@ -35,6 +35,9 @@ export type IdChangeUnsubscribeFn = () => void;
 /**
  * Sets a new callback that will get called when Installation ID changes.
  * Returns an unsubscribe function that will remove the callback when called.
+ * @param installations - The `Installations` instance.
+ * @param callback - The callback function that is invoked when FID changes.
+ * @returns A function that can be called to unsubscribe.
  *
  * @public
  */
diff --git a/packages-exp/installations-exp/src/index.ts b/packages-exp/installations-exp/src/index.ts
index 671bd467083..5aa6674dea3 100644
--- a/packages-exp/installations-exp/src/index.ts
+++ b/packages-exp/installations-exp/src/index.ts
@@ -1,3 +1,9 @@
+/**
+ * Firebase Installations
+ *
+ * @packageDocumentation
+ */
+
 /**
  * @license
  * Copyright 2019 Google LLC
diff --git a/packages-exp/messaging-exp/src/index.ts b/packages-exp/messaging-exp/src/index.ts
index 5ed03c827d4..c82af63762b 100644
--- a/packages-exp/messaging-exp/src/index.ts
+++ b/packages-exp/messaging-exp/src/index.ts
@@ -1,3 +1,9 @@
+/**
+ * Firebase Cloud Messaging
+ *
+ * @packageDocumentation
+ */
+
 /**
  * @license
  * Copyright 2017 Google LLC
diff --git a/packages-exp/performance-exp/src/index.ts b/packages-exp/performance-exp/src/index.ts
index 8e951015e75..07d00b70dac 100644
--- a/packages-exp/performance-exp/src/index.ts
+++ b/packages-exp/performance-exp/src/index.ts
@@ -1,3 +1,9 @@
+/**
+ * Firebase Performance Monitoring
+ *
+ * @packageDocumentation
+ */
+
 /**
  * @license
  * Copyright 2020 Google LLC
@@ -45,7 +51,7 @@ const DEFAULT_ENTRY_NAME = '[DEFAULT]';
 
 /**
  * Returns a FirebasePerformance instance for the given app.
- * @param app - The FirebaseApp to use.
+ * @param app - The `FirebaseApp` to use.
  * @public
  */
 export function getPerformance(
@@ -59,8 +65,8 @@ export function getPerformance(
 
 /**
  * Returns a FirebasePerformance instance for the given app. Can only be called once.
- * @param app - The FirebaseApp to use.
- * @param settings - Optional settings for the Performance instance.
+ * @param app - The `FirebaseApp` to use.
+ * @param settings - Optional settings for the `FirebasePerformance` instance.
  * @public
  */
 export function initializePerformance(
@@ -83,8 +89,8 @@ export function initializePerformance(
 }
 
 /**
- * Returns a new PerformanceTrace instance.
- * @param performance - The FirebasePerformance instance to use.
+ * Returns a new `PerformanceTrace` instance.
+ * @param performance - The `FirebasePerformance` instance to use.
  * @param name - The name of the trace.
  * @public
  */
diff --git a/packages-exp/performance-exp/src/public_types.ts b/packages-exp/performance-exp/src/public_types.ts
index 20125ae6e28..756fca2febf 100644
--- a/packages-exp/performance-exp/src/public_types.ts
+++ b/packages-exp/performance-exp/src/public_types.ts
@@ -16,6 +16,8 @@
  */
 
 /**
+ * Defines configuration options for the Performance Monitoring SDK.
+ *
  * @public
  */
 export interface PerformanceSettings {
@@ -27,6 +29,8 @@ export interface PerformanceSettings {
 }
 
 /**
+ * The Firebase Performance Monitoring service interface.
+ *
  * @public
  */
 export interface FirebasePerformance {
@@ -42,6 +46,8 @@ export interface FirebasePerformance {
 }
 
 /**
+ * The interface representing a `Trace`.
+ *
  * @public
  */
 export interface PerformanceTrace {
diff --git a/packages-exp/remote-config-exp/src/api.ts b/packages-exp/remote-config-exp/src/api.ts
index bbd6c404605..bf7937faeb0 100644
--- a/packages-exp/remote-config-exp/src/api.ts
+++ b/packages-exp/remote-config-exp/src/api.ts
@@ -31,8 +31,8 @@ import { getModularInstance } from '@firebase/util';
 
 /**
  *
- * @param app - the firebase app instance
- * @returns a remote config instance
+ * @param app - The `FirebaseApp` instance.
+ * @returns A `RemoteConfig` instance.
  *
  * @public
  */
@@ -44,7 +44,7 @@ export function getRemoteConfig(app: FirebaseApp = getApp()): RemoteConfig {
 
 /**
  * Makes the last fetched config available to the getters.
- * @param remoteConfig - the remote config instance
+ * @param remoteConfig - The `RemoteConfig` instance.
  * @returns A promise which resolves to true if the current call activated the fetched configs.
  * If the fetched configs were already activated, the promise will resolve to false.
  *
@@ -75,9 +75,9 @@ export async function activate(remoteConfig: RemoteConfig): Promise<boolean> {
 
 /**
  * Ensures the last activated config are available to the getters.
- * @param remoteConfig - the remote config instance
+ * @param remoteConfig - The `RemoteConfig` instance.
  *
- * @returns A promise that resolves when the last activated config is available to the getters
+ * @returns A promise that resolves when the last activated config is available to the getters.
  * @public
  */
 export function ensureInitialized(remoteConfig: RemoteConfig): Promise<void> {
@@ -92,7 +92,7 @@ export function ensureInitialized(remoteConfig: RemoteConfig): Promise<void> {
 
 /**
  * Fetches and caches configuration from the Remote Config service.
- * @param remoteConfig - the remote config instance
+ * @param remoteConfig - The `RemoteConfig` instance.
  * @public
  */
 export async function fetchConfig(remoteConfig: RemoteConfig): Promise<void> {
@@ -134,8 +134,8 @@ export async function fetchConfig(remoteConfig: RemoteConfig): Promise<void> {
 /**
  * Gets all config.
  *
- * @param remoteConfig - the remote config instance
- * @returns all config
+ * @param remoteConfig - The `RemoteConfig` instance.
+ * @returns All config.
  *
  * @public
  */
@@ -155,10 +155,10 @@ export function getAll(remoteConfig: RemoteConfig): Record<string, Value> {
  *
  * Convenience method for calling <code>remoteConfig.getValue(key).asBoolean()</code>.
  *
- * @param remoteConfig - the remote config instance
- * @param key - the name of the parameter
+ * @param remoteConfig - The `RemoteConfig` instance.
+ * @param key - The name of the parameter.
  *
- * @returns the value for the given key as a boolean
+ * @returns The value for the given key as a boolean.
  * @public
  */
 export function getBoolean(remoteConfig: RemoteConfig, key: string): boolean {
@@ -170,10 +170,10 @@ export function getBoolean(remoteConfig: RemoteConfig, key: string): boolean {
  *
  * Convenience method for calling <code>remoteConfig.getValue(key).asNumber()</code>.
  *
- * @param remoteConfig - the remote config instance
- * @param key - the name of the parameter
+ * @param remoteConfig - The `RemoteConfig` instance.
+ * @param key - The name of the parameter.
  *
- * @returns the value for the given key as a number
+ * @returns The value for the given key as a number.
  *
  * @public
  */
@@ -182,13 +182,13 @@ export function getNumber(remoteConfig: RemoteConfig, key: string): number {
 }
 
 /**
- * Gets the value for the given key as a String.
+ * Gets the value for the given key as a string.
  * Convenience method for calling <code>remoteConfig.getValue(key).asString()</code>.
  *
- * @param remoteConfig - the remote config instance
- * @param key - the name of the parameter
+ * @param remoteConfig - The `RemoteConfig` instance.
+ * @param key - The name of the parameter.
  *
- * @returns the value for the given key as a String
+ * @returns The value for the given key as a string.
  *
  * @public
  */
@@ -199,10 +199,10 @@ export function getString(remoteConfig: RemoteConfig, key: string): string {
 /**
  * Gets the {@link Value} for the given key.
  *
- * @param remoteConfig - the remote config instance
- * @param key - the name of the parameter
+ * @param remoteConfig - The `RemoteConfig` instance.
+ * @param key - The name of the parameter.
  *
- * @returns the value for the given key
+ * @returns The value for the given key.
  *
  * @public
  */
@@ -230,8 +230,8 @@ export function getValue(remoteConfig: RemoteConfig, key: string): Value {
 /**
  * Defines the log level to use.
  *
- * @param remoteConfig - the remote config instance
- * @param logLevel - the log level to set
+ * @param remoteConfig - The `RemoteConfig` instance.
+ * @param logLevel - The log level to set.
  *
  * @public
  */
diff --git a/packages-exp/remote-config-exp/src/api2.ts b/packages-exp/remote-config-exp/src/api2.ts
index 49065e038c3..7d0689a8561 100644
--- a/packages-exp/remote-config-exp/src/api2.ts
+++ b/packages-exp/remote-config-exp/src/api2.ts
@@ -25,7 +25,7 @@ import { getModularInstance } from '@firebase/util';
  *
  * Performs fetch and activate operations, as a convenience.
  *
- * @param remoteConfig - the remote config instance
+ * @param remoteConfig - The remote config instance.
  *
  * @returns A promise which resolves to true if the current call activated the fetched configs.
  * If the fetched configs were already activated, the promise will resolve to false.
diff --git a/packages-exp/remote-config-exp/src/index.ts b/packages-exp/remote-config-exp/src/index.ts
index 665535c968c..b51873453fe 100644
--- a/packages-exp/remote-config-exp/src/index.ts
+++ b/packages-exp/remote-config-exp/src/index.ts
@@ -1,3 +1,9 @@
+/**
+ * Firebase Remote Config
+ *
+ * @packageDocumentation
+ */
+
 /**
  * @license
  * Copyright 2020 Google LLC
diff --git a/packages/database/api-extractor.json b/packages/database/api-extractor.json
index c2a260fb043..af5554eb1e4 100644
--- a/packages/database/api-extractor.json
+++ b/packages/database/api-extractor.json
@@ -1,5 +1,5 @@
 {
     "extends": "../../config/api-extractor.json",
     // Point it to your entry point d.ts file. 
-    "mainEntryPointFilePath": "<projectFolder>/exp-types/index.d.ts"
+    "mainEntryPointFilePath": "<projectFolder>/dist/exp/index.d.ts"
 }
\ No newline at end of file
diff --git a/packages/database/exp/index.ts b/packages/database/exp/index.ts
index b2e7bc1894a..30c71177e81 100644
--- a/packages/database/exp/index.ts
+++ b/packages/database/exp/index.ts
@@ -1,3 +1,9 @@
+/**
+ * Firebase Realtime Database
+ *
+ * @packageDocumentation
+ */
+
 /**
  * @license
  * Copyright 2020 Google LLC
diff --git a/packages/firestore/exp/index.ts b/packages/firestore/exp/index.ts
index 768973e00f6..aab859b67a7 100644
--- a/packages/firestore/exp/index.ts
+++ b/packages/firestore/exp/index.ts
@@ -1,3 +1,9 @@
+/**
+ * Cloud Firestore
+ *
+ * @packageDocumentation
+ */
+
 /**
  * @license
  * Copyright 2020 Google LLC
diff --git a/packages/storage/exp/index.ts b/packages/storage/exp/index.ts
index c105d1644b7..c3027536c5d 100644
--- a/packages/storage/exp/index.ts
+++ b/packages/storage/exp/index.ts
@@ -1,3 +1,9 @@
+/**
+ * Cloud Storage for Firebase
+ *
+ * @packageDocumentation
+ */
+
 /**
  * @license
  * Copyright 2020 Google LLC
diff --git a/scripts/exp/docgen.ts b/scripts/exp/docgen.ts
index 88637ee070f..6fa9821fddc 100644
--- a/scripts/exp/docgen.ts
+++ b/scripts/exp/docgen.ts
@@ -53,6 +53,15 @@ async function generateDocs(forDevsite: boolean = false) {
     }
   );
 
+  // build database-exp
+  await spawn(
+    'yarn',
+    ['lerna', 'run', '--scope', '@firebase/database', 'build:exp'],
+    {
+      stdio: 'inherit'
+    }
+  );
+
   // generate public typings for firestore
   await spawn(
     'yarn',