chore: Enabled tsdoc error checking (#1459)

* chore: Enabled tsdoc error checking

* fix: Fixing a lint error

* fix: Minor internal doc comment updates

* fix: Updating doc comment

api-extractor.json

@@ -34,12 +34,12 @@
       },
 
       "ae-unresolved-link": {
-        "logLevel": "none"
+        "logLevel": "error"
       }
     },
     "tsdocMessageReporting": {
       "default": {
-        "logLevel": "none"
+        "logLevel": "error"
       }
     }
   }

src/app-check/app-check-api-client-internal.ts

@@ -53,8 +53,8 @@ export class AppCheckApiClient {
   /**
    * Exchange a signed custom token to App Check token
    *
-   * @param customToken The custom token to be exchanged.
-   * @param appId The mobile App ID.
+   * @param customToken - The custom token to be exchanged.
+   * @param appId - The mobile App ID.
    * @returns A promise that fulfills with a `AppCheckToken`.
    */
   public exchangeToken(customToken: string, appId: string): Promise<AppCheckToken> {
@@ -140,7 +140,7 @@ export class AppCheckApiClient {
   /**
    * Creates an AppCheckToken from the API response.
    *
-   * @param resp API response object.
+   * @param resp - API response object.
    * @returns An AppCheckToken instance.
    */
   private toAppCheckToken(resp: HttpResponse): AppCheckToken {
@@ -157,7 +157,7 @@ export class AppCheckApiClient {
   /**
    * Converts a duration string with the suffix `s` to milliseconds.
    *
-   * @param duration The duration as a string with the suffix "s" preceded by the
+   * @param duration - The duration as a string with the suffix "s" preceded by the
    * number of seconds, with fractional seconds. For example, 3 seconds with 0 nanoseconds
    * is expressed as "3s", while 3 seconds and 1 nanosecond is expressed as "3.000000001s",
    * and 3 seconds and 1 microsecond is expressed as "3.000001s".
@@ -209,8 +209,8 @@ export type AppCheckErrorCode =
 /**
  * Firebase App Check error code structure. This extends PrefixedFirebaseError.
  *
- * @param code The error code.
- * @param message The error message.
+ * @param code - The error code.
+ * @param message - The error message.
  * @constructor
  */
 export class FirebaseAppCheckError extends PrefixedFirebaseError {

src/app-check/app-check-namespace.ts

@@ -42,7 +42,7 @@ import { AppCheck as TAppCheck } from './app-check';
  * var otherAppCheck = admin.appCheck(otherApp);
  * ```
  *
- * @param app Optional app for which to return the `AppCheck` service.
+ * @param app - Optional app for which to return the `AppCheck` service.
  *   If not provided, the default `AppCheck` service is returned.
  *
  * @returns The default `AppCheck` service if no

src/app-check/app-check.ts

@@ -39,7 +39,7 @@ export class AppCheck {
   private readonly appCheckTokenVerifier: AppCheckTokenVerifier;
 
   /**
-   * @param app The app for this AppCheck service.
+   * @param app - The app for this AppCheck service.
    * @constructor
    * @internal
    */
@@ -54,11 +54,11 @@ export class AppCheck {
   }
 
   /**
-   * Creates a new {@link appCheck.AppCheckToken `AppCheckToken`} that can be sent
+   * Creates a new {@link AppCheckToken} that can be sent
    * back to a client.
    *
-   * @param appId The app ID to use as the JWT app_id.
-   * @param options Optional options object when creating a new App Check Token.
+   * @param appId - The app ID to use as the JWT app_id.
+   * @param options - Optional options object when creating a new App Check Token.
    *
    * @returns A promise that fulfills with a `AppCheckToken`.
    */
@@ -74,7 +74,7 @@ export class AppCheck {
    * fulfilled with the token's decoded claims; otherwise, the promise is
    * rejected.
    *
-   * @param appCheckToken The App Check token to verify.
+   * @param appCheckToken - The App Check token to verify.
    *
    * @returns A promise fulfilled with the token's decoded claims
    *   if the App Check token is valid; otherwise, a rejected promise.

src/app-check/index.ts

@@ -52,7 +52,7 @@ export { AppCheck } from './app-check';
  * const otherAppCheck = getAppCheck(otherApp);
  * ```
  *
- * @param app Optional app for which to return the `AppCheck` service.
+ * @param app - Optional app for which to return the `AppCheck` service.
  *   If not provided, the default `AppCheck` service is returned.
  *
  * @returns The default `AppCheck` service if no

src/app-check/token-generator.ts

@@ -45,7 +45,7 @@ export class AppCheckTokenGenerator {
   /**
    * The AppCheckTokenGenerator class constructor.
    *
-   * @param signer The CryptoSigner instance for this token generator.
+   * @param signer - The CryptoSigner instance for this token generator.
    * @constructor
    */
   constructor(signer: CryptoSigner) {
@@ -60,7 +60,7 @@ export class AppCheckTokenGenerator {
   /**
    * Creates a new custom token that can be exchanged to an App Check token.
    *
-   * @param appId The Application ID to use for the generated token.
+   * @param appId - The Application ID to use for the generated token.
    *
    * @returns A Promise fulfilled with a custom token signed with a service account key
    * that can be exchanged to an App Check token.
@@ -110,7 +110,7 @@ export class AppCheckTokenGenerator {
    * Checks if a given `AppCheckTokenOptions` object is valid. If successful, returns an object with
    * custom properties.
    *
-   * @param options An options object to be validated.
+   * @param options - An options object to be validated.
    * @returns A custom object with ttl converted to protobuf Duration string format.
    */
   private validateTokenOptions(options: AppCheckTokenOptions): {[key: string]: any} {
@@ -137,10 +137,10 @@ export class AppCheckTokenGenerator {
 }
 
 /**
- * Creates a new FirebaseAppCheckError by extracting the error code, message and other relevant
- * details from a CryptoSignerError.
+ * Creates a new `FirebaseAppCheckError` by extracting the error code, message and other relevant
+ * details from a `CryptoSignerError`.
  *
- * @param err The Error to convert into a FirebaseAppCheckError error
+ * @param err - The Error to convert into a `FirebaseAppCheckError` error
  * @returns A Firebase App Check error that can be returned to the user.
  */
 export function appCheckErrorFromCryptoSignerError(err: Error): Error {

src/app-check/token-verifier.ts

@@ -43,7 +43,7 @@ export class AppCheckTokenVerifier {
   /**
    * Verifies the format and signature of a Firebase App Check token.
    *
-   * @param token The Firebase Auth JWT token to verify.
+   * @param token - The Firebase Auth JWT token to verify.
    * @returns A promise fulfilled with the decoded claims of the Firebase App Check token.
    */
   public verifyToken(token: string): Promise<DecodedAppCheckToken> {
@@ -101,8 +101,8 @@ export class AppCheckTokenVerifier {
   /**
    * Verifies the content of a Firebase App Check JWT.
    *
-   * @param fullDecodedToken The decoded JWT.
-   * @param projectId The Firebase Project Id.
+   * @param fullDecodedToken - The decoded JWT.
+   * @param projectId - The Firebase Project Id.
    */
   private verifyContent(fullDecodedToken: DecodedToken, projectId: string | null): void {
     const header = fullDecodedToken.header;
@@ -142,7 +142,7 @@ export class AppCheckTokenVerifier {
   /**
    * Maps JwtError to FirebaseAppCheckError
    *
-   * @param error JwtError to be mapped.
+   * @param error - JwtError to be mapped.
    * @returns FirebaseAppCheckError instance.
    */
   private mapJwtErrorToAppCheckError(error: JwtError): FirebaseAppCheckError {

src/app/core.ts

@@ -25,7 +25,7 @@ import { Credential } from './credential';
 export interface AppOptions {
 
   /**
-   * A {@link Credential `Credential`} object used to
+   * A {@link firebase-admin.app#Credential} object used to
    * authenticate the Admin SDK.
    *
    * See {@link https://firebase.google.com/docs/admin/setup#initialize_the_sdk | Initialize the SDK}
@@ -155,9 +155,8 @@ export interface FirebaseError {
    * A string value containing the execution backtrace when the error originally
    * occurred.
    *
-   * This information can be useful to you and can be sent to
-   * {@link https://firebase.google.com/support/ Firebase Support} to help
-   * explain the cause of an error.
+   * This information can be useful for troubleshooting the cause of the error with
+   * {@link https://firebase.google.com/support | Firebase Support}.
    */
   stack?: string;
 

src/app/credential-factory.ts

@@ -48,7 +48,7 @@ const globalRefreshTokenCreds: { [key: string]: RefreshTokenCredential } = {};
  * });
  * ```
  *
- * @param httpAgent Optional {@link https://nodejs.org/api/http.html#http_class_http_agent | HTTP Agent}
+ * @param httpAgent - Optional {@link https://nodejs.org/api/http.html#http_class_http_agent | HTTP Agent}
  *   to be used when retrieving access tokens from Google token servers.
  *
  * @returns A credential authenticated via Google
@@ -93,9 +93,9 @@ export function applicationDefault(httpAgent?: Agent): Credential {
  * });
  * ```
  *
- * @param serviceAccountPathOrObject The path to a service
+ * @param serviceAccountPathOrObject - The path to a service
  *   account key JSON file or an object representing a service account key.
- * @param httpAgent Optional {@link https://nodejs.org/api/http.html#http_class_http_agent | HTTP Agent}
+ * @param httpAgent - Optional {@link https://nodejs.org/api/http.html#http_class_http_agent | HTTP Agent}
  *   to be used when retrieving access tokens from Google token servers.
  *
  * @returns A credential authenticated via the
@@ -129,10 +129,10 @@ export function cert(serviceAccountPathOrObject: string | ServiceAccount, httpAg
  * });
  * ```
  *
- * @param refreshTokenPathOrObject The path to a Google
+ * @param refreshTokenPathOrObject - The path to a Google
  *   OAuth2 refresh token JSON file or an object representing a Google OAuth2
  *   refresh token.
- * @param httpAgent Optional {@link https://nodejs.org/api/http.html#http_class_http_agent | HTTP Agent}
+ * @param httpAgent - Optional {@link https://nodejs.org/api/http.html#http_class_http_agent | HTTP Agent}
  *   to be used when retrieving access tokens from Google token servers.
  *
  * @returns A credential authenticated via the

src/app/credential-internal.ts

@@ -68,9 +68,9 @@ export class ServiceAccountCredential implements Credential {
   /**
    * Creates a new ServiceAccountCredential from the given parameters.
    *
-   * @param serviceAccountPathOrObject Service account json object or path to a service account json file.
-   * @param httpAgent Optional http.Agent to use when calling the remote token server.
-   * @param implicit An optinal boolean indicating whether this credential was implicitly discovered from the
+   * @param serviceAccountPathOrObject - Service account json object or path to a service account json file.
+   * @param httpAgent - Optional http.Agent to use when calling the remote token server.
+   * @param implicit - An optinal boolean indicating whether this credential was implicitly discovered from the
    *   environment, as opposed to being explicitly specified by the developer.
    *
    * @constructor
@@ -248,10 +248,11 @@ export class RefreshTokenCredential implements Credential {
   /**
    * Creates a new RefreshTokenCredential from the given parameters.
    *
-   * @param refreshTokenPathOrObject Refresh token json object or path to a refresh token (user credentials) json file.
-   * @param httpAgent Optional http.Agent to use when calling the remote token server.
-   * @param implicit An optinal boolean indicating whether this credential was implicitly discovered from the
-   *   environment, as opposed to being explicitly specified by the developer.
+   * @param refreshTokenPathOrObject - Refresh token json object or path to a refresh token
+   *   (user credentials) json file.
+   * @param httpAgent - Optional http.Agent to use when calling the remote token server.
+   * @param implicit - An optinal boolean indicating whether this credential was implicitly
+   *   discovered from the environment, as opposed to being explicitly specified by the developer.
    *
    * @constructor
    */
@@ -338,7 +339,7 @@ class RefreshToken {
  * instances that were loaded from well-known files or environment variables, rather than being explicitly
  * instantiated.
  *
- * @param credential The credential instance to check.
+ * @param credential - The credential instance to check.
  */
 export function isApplicationDefault(credential?: Credential): boolean {
   return credential instanceof ComputeEngineCredential ||
@@ -368,10 +369,10 @@ export function getApplicationDefault(httpAgent?: Agent): Credential {
  * If no property exists by the given "key", looks for a property identified by "alt", and copies it instead.
  * This can be used to implement behaviors such as "copy property myKey or my_key".
  *
- * @param to Target object to copy the property into.
- * @param from Source object to copy the property from.
- * @param key Name of the property to copy.
- * @param alt Alternative name of the property to copy.
+ * @param to - Target object to copy the property into.
+ * @param from - Source object to copy the property from.
+ * @param key - Name of the property to copy.
+ * @param alt - Alternative name of the property to copy.
  */
 function copyAttr(to: {[key: string]: any}, from: {[key: string]: any}, key: string, alt: string): void {
   const tmp = from[key] || from[alt];

src/app/credential.ts

@@ -34,8 +34,7 @@ export interface GoogleOAuthAccessToken {
  * 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`}.
+ * use the default implementations provided by the `firebase-admin/app` module.
  */
 export interface Credential {
   /**

src/app/firebase-app.ts

@@ -117,7 +117,7 @@ export class FirebaseAppInternals {
   /**
    * Adds a listener that is called each time a token changes.
    *
-   * @param listener The listener that will be called with each new token.
+   * @param listener - The listener that will be called with each new token.
    */
   public addAuthTokenListener(listener: (token: string) => void): void {
     this.tokenListeners_.push(listener);
@@ -129,7 +129,7 @@ export class FirebaseAppInternals {
   /**
    * Removes a token listener.
    *
-   * @param listener The listener to remove.
+   * @param listener - The listener to remove.
    */
   public removeAuthTokenListener(listener: (token: string) => void): void {
     this.tokenListeners_ = this.tokenListeners_.filter((other) => other !== listener);

src/app/firebase-namespace.ts

@@ -53,11 +53,11 @@ export class FirebaseNamespaceInternals {
   /**
    * Initializes the App instance.
    *
-   * @param options Optional options for the App instance. If none present will try to initialize
+   * @param options - Optional options for the App instance. If none present will try to initialize
    *   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.
+   * @param appName - Optional name of the FirebaseApp instance.
    *
    * @returns A new App instance.
    */
@@ -70,7 +70,7 @@ export class FirebaseNamespaceInternals {
    * Returns the App instance with the provided name (or the default App instance
    * if no name is provided).
    *
-   * @param appName Optional name of the FirebaseApp instance to return.
+   * @param appName - Optional name of the FirebaseApp instance to return.
    * @returns The App instance which has the provided name.
    */
   public app(appName?: string): App {
@@ -284,11 +284,11 @@ export class FirebaseNamespace {
   /**
    * Initializes the FirebaseApp instance.
    *
-   * @param options Optional options for the FirebaseApp instance.
+   * @param options - Optional options for the FirebaseApp instance.
    *   If none present will try to initialize 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.
+   * @param appName - Optional name of the FirebaseApp instance.
    *
    * @returns A new FirebaseApp instance.
    */
@@ -300,7 +300,7 @@ export class FirebaseNamespace {
    * Returns the FirebaseApp instance with the provided name (or the default FirebaseApp instance
    * if no name is provided).
    *
-   * @param appName Optional name of the FirebaseApp instance to return.
+   * @param appName - Optional name of the FirebaseApp instance to return.
    * @returns The FirebaseApp instance which has the provided name.
    */
   public app(appName?: string): App {