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
firebase · Apr 9, 2021 · 9df03c9 · 9df03c9
1 parent 626c05b
commit 9df03c9
Show file tree

Hide file tree

Showing 20 changed files with 113 additions and 30 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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"
 }
diff --git 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
@@ -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
@@ -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
@@ -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',