docs: hide entries that are marked @docs-private (#61105)

mmalerba · AndrewKushnir · commit 6ce2672e651e · 2025-05-05T08:44:05.000-07:00
PR Close #61105
diff --git a/adev/shared-docs/pipeline/api-gen/manifest/generate_manifest.ts b/adev/shared-docs/pipeline/api-gen/manifest/generate_manifest.ts
@@ -7,7 +7,7 @@
  */
 
 // @ts-ignore This compiles fine, but Webstorm doesn't like the ESM import in a CJS context.
-import type {DocEntry, EntryCollection, JsDocTagEntry, FunctionEntry} from '@angular/compiler-cli';
+import type {DocEntry, EntryCollection, FunctionEntry, JsDocTagEntry} from '@angular/compiler-cli';
 
 export interface ManifestEntry {
   name: string;
@@ -43,6 +43,11 @@ function hasTag(entry: DocEntry | FunctionEntry, tag: string, every = false) {
   return jsdocTags.some(hasTagName);
 }
 
+/** Gets whether the given entry is hidden. */
+export function isHiddenEntry<T extends DocEntry | FunctionEntry>(entry: T): boolean {
+  return hasTag(entry, 'docs-private', /* every */ true);
+}
+
 /** Gets whether the given entry is deprecated in the manifest. */
 function isDeprecated(entry: DocEntry): boolean {
   return hasTag(entry, 'deprecated', /* every */ true);
@@ -65,13 +70,15 @@ function isExperimental(entry: DocEntry): boolean {
 export function generateManifest(apiCollections: EntryCollection[]): Manifest {
   const manifest: Manifest = [];
   for (const collection of apiCollections) {
-    const entries = collection.entries.map((entry: DocEntry) => ({
-      name: entry.name,
-      type: entry.entryType,
-      isDeprecated: isDeprecated(entry),
-      isDeveloperPreview: isDeveloperPreview(entry),
-      isExperimental: isExperimental(entry),
-    }));
+    const entries = collection.entries
+      .filter((entry) => !isHiddenEntry(entry))
+      .map((entry: DocEntry) => ({
+        name: entry.name,
+        type: entry.entryType,
+        isDeprecated: isDeprecated(entry),
+        isDeveloperPreview: isDeveloperPreview(entry),
+        isExperimental: isExperimental(entry),
+      }));
 
     const existingEntry = manifest.find((entry) => entry.moduleName === collection.moduleName);
     if (existingEntry) {
diff --git a/adev/shared-docs/pipeline/api-gen/rendering/entities/categorization.ts b/adev/shared-docs/pipeline/api-gen/rendering/entities/categorization.ts
@@ -28,7 +28,6 @@ import {CliCommand} from '../cli-entities';
 
 import {
   ClassEntryRenderable,
-  CliCommandRenderable,
   ConstantEntryRenderable,
   DecoratorEntryRenderable,
   DocEntryRenderable,
@@ -132,6 +131,11 @@ export function isSetterEntry(entry: MemberEntry): entry is PropertyEntry {
   return entry.memberType === MemberType.Setter;
 }
 
+/** Gets whether the given entry is hidden. */
+export function isHiddenEntry<T extends HasJsDocTags>(entry: T): boolean {
+  return hasTag(entry, 'docs-private', /* every */ true);
+}
+
 /** Gets whether the given entry is deprecated. */
 export function isDeprecatedEntry<T extends HasJsDocTags>(entry: T) {
   return hasTag(entry, 'deprecated', /* every */ true);
@@ -169,7 +173,6 @@ function hasTag<T extends HasJsDocTags | FunctionEntry>(entry: T, tag: string, e
 }
 
 /** Gets whether the given entry is a cli entry. */
-export function isCliEntry(entry: unknown): entry is CliCommandRenderable;
 export function isCliEntry(entry: unknown): entry is CliCommand {
   return (entry as CliCommand).command !== undefined;
 }
diff --git a/adev/shared-docs/pipeline/api-gen/rendering/index.ts b/adev/shared-docs/pipeline/api-gen/rendering/index.ts
@@ -10,7 +10,7 @@ import {existsSync, mkdirSync, readFileSync, writeFileSync} from 'fs';
 import path from 'path';
 import {CliCommand} from './cli-entities';
 import {DocEntry} from './entities';
-import {isCliEntry} from './entities/categorization';
+import {isCliEntry, isHiddenEntry} from './entities/categorization';
 import {configureMarkedGlobally} from './marked/configuration';
 import {getRenderable} from './processing';
 import {renderEntry} from './rendering';
@@ -22,7 +22,7 @@ interface EntryCollection {
   moduleName: string;
   moduleLabel?: string;
   normalizedModuleName: string;
-  entries: DocEntry[];
+  entries: DocEntry[] | CliCommand[];
   symbols: Map<string, string>;
 }
 
@@ -113,7 +113,9 @@ async function main() {
   const entryCollections: EntryCollection[] = parseEntryData(srcs.split(','));
 
   for (const collection of entryCollections) {
-    const extractedEntries = collection.entries;
+    const extractedEntries = collection.entries.filter(
+      (entry) => isCliEntry(entry) || !isHiddenEntry(entry),
+    );
 
     // Setting the symbols are a global context for the rendering templates of this entry
     setSymbols(collection.symbols);
@@ -126,10 +128,7 @@ async function main() {
     const htmlOutputs = renderableEntries.map(renderEntry);
 
     for (let i = 0; i < htmlOutputs.length; i++) {
-      const filename = getNormalizedFilename(
-        collection.normalizedModuleName,
-        collection.entries[i],
-      );
+      const filename = getNormalizedFilename(collection.normalizedModuleName, extractedEntries[i]);
       const outputPath = path.join(outputFilenameExecRootRelativePath, filename);
 
       // in case the output path is nested, ensure the directory exists
diff --git a/adev/shared-docs/pipeline/api-gen/rendering/processing.ts b/adev/shared-docs/pipeline/api-gen/rendering/processing.ts
@@ -37,11 +37,16 @@ import {
 } from './transforms/jsdoc-transforms';
 import {addModuleName} from './transforms/module-name';
 import {getTypeAliasRenderable} from './transforms/type-alias-transforms';
+import {CliCommand} from './cli-entities';
 
 export function getRenderable(
-  entry: DocEntry,
+  entry: DocEntry | CliCommand,
   moduleName: string,
 ): DocEntryRenderable | CliCommandRenderable {
+  if (isCliEntry(entry)) {
+    return getCliRenderable(entry);
+  }
+
   if (isClassEntry(entry)) {
     return getClassRenderable(entry, moduleName);
   }
@@ -66,9 +71,6 @@ export function getRenderable(
   if (isInitializerApiFunctionEntry(entry)) {
     return getInitializerApiFunctionRenderable(entry, moduleName);
   }
-  if (isCliEntry(entry)) {
-    return getCliRenderable(entry);
-  }
 
   // Fallback to an uncategorized renderable.
   return setEntryFlags(
diff --git a/adev/shared-docs/pipeline/api-gen/rendering/transforms/member-transforms.ts b/adev/shared-docs/pipeline/api-gen/rendering/transforms/member-transforms.ts
@@ -7,6 +7,7 @@
  */
 
 import {MemberEntry, MemberTags, MemberType} from '../entities';
+import {isHiddenEntry} from '../entities/categorization';
 
 import {HasMembers, HasModuleName, HasRenderableMembers} from '../entities/traits';
 
@@ -65,13 +66,15 @@ export function mergeGettersAndSetters(members: MemberEntry[]): MemberEntry[] {
 export function addRenderableMembers<T extends HasMembers & HasModuleName>(
   entry: T,
 ): T & HasRenderableMembers {
-  const members = entry.members.map((member) =>
-    setEntryFlags(
-      addHtmlDescription(
-        addHtmlUsageNotes(addHtmlJsDocTagComments(addModuleName(member, entry.moduleName))),
+  const members = entry.members
+    .filter((member) => !isHiddenEntry(member))
+    .map((member) =>
+      setEntryFlags(
+        addHtmlDescription(
+          addHtmlUsageNotes(addHtmlJsDocTagComments(addModuleName(member, entry.moduleName))),
+        ),
       ),
-    ),
-  );
+    );
 
   return {
     ...entry,
