fix(docs-infra): prevent duplicate description rendering for block API entries

Block entries (@if, @defer, @for,@let, @switch) were falling back to the generic
DocsReference template, causing the description to appear twice - once in
the header section and once in the main content area.

This commit adds a dedicated rendering path for block entries:
- Creates BlockEntryRenderable type and associated transforms
- Adds BlockReference template that uses RawHtml directly
- Modifies HeaderApi to accept hideDescription prop
- Updates processing and rendering pipelines to handle blocks

The fix ensures block documentation displays only one description section
while preserving the existing behavior for all other API entry types.

Update adev/shared-docs/pipeline/api-gen/rendering/transforms/block-transforms.mts

Co-authored-by: Matthieu Riegler <kyro38@gmail.com>

Author: 2 people

adev/shared-docs/pipeline/api-gen/rendering/entities.mts

@@ -161,6 +161,9 @@ export type FunctionEntry = FunctionDefinitionEntry &
     implementation: FunctionSignatureMetadata;
   };
 
+/** Documentation entity for a block. */
+export interface BlockEntry extends DocEntry {}
+
 /** Interface describing a function with overload signatures. */
 export interface FunctionDefinitionEntry {
   name: string;

adev/shared-docs/pipeline/api-gen/rendering/entities/categorization.mts

@@ -7,6 +7,7 @@
  */
 
 import {
+  BlockEntry,
   ClassEntry,
   ConstantEntry,
   DecoratorEntry,
@@ -27,6 +28,7 @@ import {
 import {CliCommand} from '../cli-entities.mjs';
 
 import {
+  BlockEntryRenderable,
   ClassEntryRenderable,
   ConstantEntryRenderable,
   DecoratorEntryRenderable,
@@ -107,6 +109,13 @@ export function isFunctionEntry(entry: DocEntry): entry is FunctionEntry {
   return entry.entryType === EntryType.Function;
 }
 
+/** Gets whether the given entry represents a block */
+export function isBlockEntry(entry: DocEntryRenderable): entry is BlockEntryRenderable;
+export function isBlockEntry(entry: DocEntry): entry is BlockEntry;
+export function isBlockEntry(entry: DocEntry): entry is BlockEntry {
+  return entry.entryType === EntryType.Block;
+}
+
 export function isInitializerApiFunctionEntry(
   entry: DocEntryRenderable,
 ): entry is InitializerApiFunctionRenderable;

adev/shared-docs/pipeline/api-gen/rendering/entities/renderables.mts

@@ -21,6 +21,7 @@ import {
   ParameterEntry,
   PipeEntry,
   TypeAliasEntry,
+  EntryType,
 } from '../entities.mjs';
 
 import {CliCommand, CliOption} from '../cli-entities.mjs';
@@ -106,6 +107,9 @@ export type FunctionSignatureMetadataRenderable = FunctionSignatureMetadata &
     params: ParameterEntryRenderable[];
   };
 
+/** Documentation entity for a block augmented with transformed content for rendering. */
+export type BlockEntryRenderable = DocEntry & DocEntryRenderable;
+
 /** Sub-entry for a single class or enum member augmented with transformed content for rendering. */
 export interface MemberEntryRenderable extends MemberEntry {
   htmlDescription: string;

adev/shared-docs/pipeline/api-gen/rendering/processing.mts

@@ -19,6 +19,7 @@ import {
   isInitializerApiFunctionEntry,
   isInterfaceEntry,
   isTypeAliasEntry,
+  isBlockEntry,
 } from './entities/categorization.mjs';
 import {CliCommandRenderable, DocEntryRenderable} from './entities/renderables.mjs';
 import {getClassRenderable} from './transforms/class-transforms.mjs';
@@ -39,6 +40,7 @@ import {
 import {addModuleName} from './transforms/module-name.mjs';
 import {addRepo} from './transforms/repo.mjs';
 import {getTypeAliasRenderable} from './transforms/type-alias-transforms.mjs';
+import {getBlockRenderable} from './transforms/block-transforms.mjs';
 
 export async function getRenderable(
   entry: DocEntry | CliCommand,
@@ -73,6 +75,9 @@ export async function getRenderable(
   if (isInitializerApiFunctionEntry(entry)) {
     return getInitializerApiFunctionRenderable(entry, moduleName, repo);
   }
+  if (isBlockEntry(entry)) {
+    return getBlockRenderable(entry, moduleName, repo);
+  }
 
   // Fallback to an uncategorized renderable.
   return setEntryFlags(

adev/shared-docs/pipeline/api-gen/rendering/rendering.mts

@@ -18,6 +18,7 @@ import {
   isInitializerApiFunctionEntry,
   isInterfaceEntry,
   isTypeAliasEntry,
+  isBlockEntry,
 } from './entities/categorization.mjs';
 import {CliCommandRenderable, DocEntryRenderable} from './entities/renderables.mjs';
 import {ClassReference} from './templates/class-reference';
@@ -30,6 +31,7 @@ import {InitializerApiFunction} from './templates/initializer-api-function';
 import {TypeAliasReference} from './templates/type-alias-reference';
 import {DecoratorReference} from './templates/decorator-reference';
 import {setCurrentSymbol} from './symbol-context.mjs';
+import {BlockReference} from './templates/block-reference';
 
 /** Given a doc entry, get the transformed version of the entry for rendering. */
 export function renderEntry(renderable: DocEntryRenderable | CliCommandRenderable): string {
@@ -59,6 +61,9 @@ export function renderEntry(renderable: DocEntryRenderable | CliCommandRenderabl
   if (isInitializerApiFunctionEntry(renderable)) {
     return render(InitializerApiFunction(renderable));
   }
+  if (isBlockEntry(renderable)) {
+    return render(BlockReference(renderable));
+  }
 
   // Fall back rendering nothing while in development.
   return render(DocsReference(renderable));

adev/shared-docs/pipeline/api-gen/rendering/templates/block-reference.tsx

@@ -0,0 +1,23 @@
+/*!
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import {h} from 'preact';
+import {BlockEntryRenderable} from '../entities/renderables.mjs';
+import {HeaderApi} from './header-api';
+import {RawHtml} from './raw-html';
+import {API_REFERENCE_CONTAINER} from '../styling/css-classes.mjs';
+
+/** Component to render a block API reference document. */
+export function BlockReference(entry: BlockEntryRenderable) {
+  return (
+    <div className={API_REFERENCE_CONTAINER}>
+      <HeaderApi entry={entry} hideDescription={true} />
+      <RawHtml value={entry.htmlDescription} />
+    </div>
+  );
+}

adev/shared-docs/pipeline/api-gen/rendering/templates/header-api.tsx

@@ -21,6 +21,7 @@ import {DocsPillRow} from './docs-pill-row';
 export function HeaderApi(props: {
   entry: DocEntryRenderable | PipeEntryRenderable;
   showFullDescription?: boolean;
+  hideDescription?: boolean;
 }) {
   const entry = props.entry;
 
@@ -60,12 +61,14 @@ export function HeaderApi(props: {
         )}
       </div>
 
-      <section
-        className={'docs-reference-description'}
-        dangerouslySetInnerHTML={{
-          __html: props.showFullDescription ? entry.htmlDescription : entry.shortHtmlDescription,
-        }}
-      ></section>
+      {!props.hideDescription && (
+        <section
+          className={'docs-reference-description'}
+          dangerouslySetInnerHTML={{
+            __html: props.showFullDescription ? entry.htmlDescription : entry.shortHtmlDescription,
+          }}
+        ></section>
+      )}
 
       <DocsPillRow links={entry.additionalLinks} />
     </header>

adev/shared-docs/pipeline/api-gen/rendering/transforms/block-transforms.mts

@@ -0,0 +1,36 @@
+/*!
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import {DocEntry} from '../entities.mjs';
+import {BlockEntryRenderable} from '../entities/renderables.mjs';
+import {
+  addHtmlAdditionalLinks,
+  addHtmlDescription,
+  addHtmlJsDocTagComments,
+  addHtmlUsageNotes,
+  setEntryFlags,
+} from './jsdoc-transforms.mjs';
+import {addModuleName} from './module-name.mjs';
+import {addRepo} from './repo.mjs';
+
+/** Given an unprocessed block entry, get the fully renderable block entry. */
+export function getBlockRenderable(
+  blockEntry: DocEntry,
+  moduleName: string,
+  repo: string,
+): BlockEntryRenderable {
+  return setEntryFlags(
+    addHtmlAdditionalLinks(
+      addHtmlDescription(
+        addHtmlUsageNotes(
+          addHtmlJsDocTagComments(addRepo(addModuleName(blockEntry, moduleName), repo)),
+        ),
+      ),
+    ),
+  );
+}