chore(docs): add custom @excludeFromDocs tag to filter generated docs

Author: jonathanedey

etc/firebase-admin.auth.api.md

@@ -31,7 +31,7 @@ export interface AllowByDefault {
 // @public
 export interface AllowByDefaultWrap {
     allowByDefault: AllowByDefault;
-    // @alpha (undocumented)
+    // (undocumented)
     allowlistOnly?: never;
 }
 
@@ -42,7 +42,7 @@ export interface AllowlistOnly {
 
 // @public
 export interface AllowlistOnlyWrap {
-    // @alpha (undocumented)
+    // (undocumented)
     allowByDefault?: never;
     allowlistOnly: AllowlistOnly;
 }
@@ -196,7 +196,7 @@ export abstract class BaseAuth {
     setCustomUserClaims(uid: string, customUserClaims: object | null): Promise<void>;
     updateProviderConfig(providerId: string, updatedConfig: UpdateAuthProviderRequest): Promise<AuthProviderConfig>;
     updateUser(uid: string, properties: UpdateRequest): Promise<UserRecord>;
-    // @alpha (undocumented)
+    // (undocumented)
     _verifyAuthBlockingToken(token: string, audience?: string): Promise<DecodedAuthBlockingToken>;
     verifyIdToken(idToken: string, checkRevoked?: boolean): Promise<DecodedIdToken>;
     verifySessionCookie(sessionCookie: string, checkRevoked?: boolean): Promise<DecodedIdToken>;
@@ -257,7 +257,7 @@ export interface CustomStrengthOptionsConfig {
     requireUppercase?: boolean;
 }
 
-// @alpha (undocumented)
+// @public (undocumented)
 export interface DecodedAuthBlockingToken {
     // (undocumented)
     [key: string]: any;

etc/firebase-admin.functions.api.md

@@ -8,15 +8,15 @@ import { Agent } from 'http';
 
 // @public
 export interface AbsoluteDelivery {
-    // @alpha (undocumented)
+    // (undocumented)
     scheduleDelaySeconds?: never;
     scheduleTime?: Date;
 }
 
 // @public
 export interface DelayDelivery {
     scheduleDelaySeconds?: number;
-    // @alpha (undocumented)
+    // (undocumented)
     scheduleTime?: never;
 }
 

generate-reports.js

@@ -73,11 +73,40 @@ async function generateReportForEntryPoint(entryPoint, filePath) {
     }
 
     console.error(`API Extractor completed successfully`);
+
+    // Strip @excludeFromDocs APIs from the generated docModel so they aren't documented in reference docs.
+    const apiJsonPath = path.resolve('temp', `${safeName}.api.json`);
+    await stripHiddenDocsFromApiJson(apiJsonPath);
   } finally {
     await fs.unlink(tempConfigFile);
   }
 }
 
+async function stripHiddenDocsFromApiJson(apiJsonPath) {
+  if (!await fs.exists(apiJsonPath)) {
+    return;
+  }
+  const content = await fs.readFile(apiJsonPath, 'utf8');
+  const data = JSON.parse(content);
+
+  let removedCount = 0;
+  function removeHidden(node) {
+    if (node.members) {
+      const originalLength = node.members.length;
+      // Filter out any member whose docComment includes @excludeFromDocs
+      node.members = node.members.filter(m => !(m.docComment && /@excludeFromDocs\b/.test(m.docComment)));
+      removedCount += (originalLength - node.members.length);
+      node.members.forEach(removeHidden);
+    }
+  }
+
+  removeHidden(data);
+  if (removedCount > 0) {
+    console.log(`Removed ${removedCount} @excludeFromDocs items from ${path.basename(apiJsonPath)}`);
+    await fs.writeFile(apiJsonPath, JSON.stringify(data, null, 2));
+  }
+}
+
 (async () => {
   try {
     await generateReports();

src/auth/auth-config.ts

@@ -1631,7 +1631,9 @@ export interface AllowByDefaultWrap {
    * Allow every region by default.
    */
   allowByDefault: AllowByDefault;
-  /** @alpha */
+  /**
+   * @excludeFromDocs
+   */
   allowlistOnly?: never;
 }
 
@@ -1644,7 +1646,9 @@ export interface AllowlistOnlyWrap {
    * allowlist.
    */
   allowlistOnly: AllowlistOnly;
-  /** @alpha */
+  /**
+   * @excludeFromDocs
+   */
   allowByDefault?: never;
 }
 

src/auth/base-auth.ts

@@ -1096,7 +1096,9 @@ export abstract class BaseAuth {
     return Promise.reject(new FirebaseAuthError(authClientErrorCode.INVALID_PROVIDER_ID));
   }
 
-  /** @alpha */
+  /**
+   * @excludeFromDocs
+   */
   // eslint-disable-next-line @typescript-eslint/naming-convention
   public _verifyAuthBlockingToken(
     token: string,

src/auth/token-verifier.ts

@@ -177,7 +177,9 @@ export interface DecodedIdToken {
   [key: string]: any;
 }
 
-/** @alpha */
+/**
+ * @excludeFromDocs
+ */
 export interface DecodedAuthBlockingSharedUserInfo {
   uid: string;
   display_name?: string;
@@ -186,18 +188,24 @@ export interface DecodedAuthBlockingSharedUserInfo {
   phone_number?: string;
 }
 
-/** @alpha */
+/**
+ * @excludeFromDocs
+ */
 export interface DecodedAuthBlockingMetadata {
   creation_time?: number;
   last_sign_in_time?: number;
 }
 
-/** @alpha */
+/**
+ * @excludeFromDocs
+ */
 export interface DecodedAuthBlockingUserInfo extends DecodedAuthBlockingSharedUserInfo {
   provider_id: string;
 }
 
-/** @alpha */
+/**
+ * @excludeFromDocs
+ */
 export interface DecodedAuthBlockingMfaInfo {
   uid: string;
   display_name?: string;
@@ -206,12 +214,16 @@ export interface DecodedAuthBlockingMfaInfo {
   factor_id?: string;
 }
 
-/** @alpha */
+/**
+ * @excludeFromDocs
+ */
 export interface DecodedAuthBlockingEnrolledFactors {
   enrolled_factors?: DecodedAuthBlockingMfaInfo[];
 }
 
-/** @alpha */
+/**
+ * @excludeFromDocs
+ */
 export interface DecodedAuthBlockingUserRecord extends DecodedAuthBlockingSharedUserInfo {
   email_verified?: boolean;
   disabled?: boolean;
@@ -226,7 +238,9 @@ export interface DecodedAuthBlockingUserRecord extends DecodedAuthBlockingShared
   [key: string]: any;
 }
 
-/** @alpha */
+/**
+ * @excludeFromDocs
+ */
 export interface DecodedAuthBlockingToken {
   aud: string;
   exp: number;
@@ -333,7 +347,7 @@ export class FirebaseTokenVerifier {
   private readonly signatureVerifier: SignatureVerifier;
 
   constructor(clientCertUrl: string, private issuer: string, private tokenInfo: FirebaseTokenInfo,
-              private readonly app: App) {
+    private readonly app: App) {
 
     if (!validator.isURL(clientCertUrl)) {
       throw new FirebaseAuthError(
@@ -410,7 +424,9 @@ export class FirebaseTokenVerifier {
       });
   }
 
-  /** @alpha */
+  /**
+   * @excludeFromDocs
+   */
   // eslint-disable-next-line @typescript-eslint/naming-convention
   public _verifyAuthBlockingToken(
     jwtToken: string,
@@ -448,7 +464,7 @@ export class FirebaseTokenVerifier {
           );
         }
         return Promise.resolve(projectId);
-      })
+      });
   }
 
   private decodeAndVerify(
@@ -521,10 +537,10 @@ export class FirebaseTokenVerifier {
         '"' + header.alg + '".' + verifyJwtTokenDocsMessage;
     } else if (typeof audience !== 'undefined' && !(payload.aud as string).includes(audience)) {
       errorMessage = `${this.tokenInfo.jwtName} has incorrect "aud" (audience) claim. Expected "` +
-      audience + '" but got "' + payload.aud + '".' + verifyJwtTokenDocsMessage;
+        audience + '" but got "' + payload.aud + '".' + verifyJwtTokenDocsMessage;
     } else if (typeof audience === 'undefined' && payload.aud !== projectId) {
       errorMessage = `${this.tokenInfo.jwtName} has incorrect "aud" (audience) claim. Expected "` +
-      projectId + '" but got "' + payload.aud + '".' + projectIdMatchMessage +
+        projectId + '" but got "' + payload.aud + '".' + projectIdMatchMessage +
         verifyJwtTokenDocsMessage;
     } else if (payload.iss !== this.issuer + projectId) {
       errorMessage = `${this.tokenInfo.jwtName} has incorrect "iss" (issuer) claim. Expected ` +

src/functions/functions-api.ts

@@ -24,7 +24,9 @@ export interface DelayDelivery {
    * This delay is added to the current time.
    */
   scheduleDelaySeconds?: number;
-  /** @alpha */
+  /**
+   * @excludeFromDocs
+   */
   scheduleTime?: never;
 }
 
@@ -36,7 +38,9 @@ export interface AbsoluteDelivery {
    * The time when the task is scheduled to be attempted or retried.
    */
   scheduleTime?: Date;
-  /** @alpha */
+  /**
+   * @excludeFromDocs
+   */
   scheduleDelaySeconds?: never;
 }
 

tsdoc.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
+  "tagDefinitions": [
+    {
+      "tagName": "@excludeFromDocs",
+      "syntaxKind": "modifier"
+    }
+  ]
+}