docs(docs-infra): Improve doc support for pipes. (angular#60926)

This commits adds the pipe usage and the impure pipe mention.

PR Close angular#60926

Author: JeanMeche

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

@@ -133,7 +133,8 @@ export interface DirectiveEntry extends ClassEntry {
 export interface PipeEntry extends ClassEntry {
   pipeName: string;
   isStandalone: boolean;
-  // TODO: add `isPure`.
+  isPure: boolean;
+  usage: string;
 }
 
 export interface FunctionSignatureMetadata extends DocEntry {

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

@@ -18,6 +18,7 @@ import {
   JsDocTagEntry,
   MemberEntry,
   ParameterEntry,
+  PipeEntry,
   TypeAliasEntry,
 } from '../entities';
 
@@ -60,6 +61,12 @@ export type ClassEntryRenderable = ClassEntry &
     members: MemberEntryRenderable[];
   };
 
+export type PipeEntryRenderable = PipeEntry &
+  DocEntryRenderable &
+  HasRenderableToc & {
+    members: MemberEntryRenderable[];
+  };
+
 export type DecoratorEntryRenderable = DecoratorEntry &
   DocEntryRenderable &
   HasRenderableToc & {

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

@@ -7,19 +7,43 @@
  */
 
 import {Fragment, h} from 'preact';
-import {ClassEntryRenderable, DecoratorEntryRenderable} from '../entities/renderables';
+import {
+  ClassEntryRenderable,
+  DecoratorEntryRenderable,
+  PipeEntryRenderable,
+} from '../entities/renderables';
 import {ClassMemberList} from './class-member-list';
 import {HeaderApi} from './header-api';
-import {API_REFERENCE_CONTAINER, REFERENCE_MEMBERS} from '../styling/css-classes';
+import {
+  API_REFERENCE_CONTAINER,
+  REFERENCE_MEMBERS,
+  SECTION_CONTAINER,
+} from '../styling/css-classes';
 import {SectionDescription} from './section-description';
 import {SectionUsageNotes} from './section-usage-notes';
 import {SectionApi} from './section-api';
+import {SectionHeading} from './section-heading';
+import {PipeEntry} from '../entities';
+import {codeToHtml} from '../shiki/shiki';
+import {RawHtml} from './raw-html';
 
 /** Component to render a class API reference document. */
-export function ClassReference(entry: ClassEntryRenderable | DecoratorEntryRenderable) {
+export function ClassReference(
+  entry: ClassEntryRenderable | DecoratorEntryRenderable | PipeEntryRenderable,
+) {
   return (
     <div className={API_REFERENCE_CONTAINER}>
       <HeaderApi entry={entry} />
+      {entry.entryType === 'pipe' ? (
+        <>
+          <div className={SECTION_CONTAINER + ' docs-reference-api-section'}>
+            <SectionHeading name="Pipe usage" />
+            <RawHtml value={codeToHtml((entry as PipeEntry).usage, 'angular-html')} />
+          </div>
+        </>
+      ) : (
+        ''
+      )}
       <SectionApi entry={entry} />
       {entry.members.length > 0 ? (
         <div class={REFERENCE_MEMBERS}>

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

@@ -7,8 +7,8 @@
  */
 
 import {h} from 'preact';
-import {EntryType, isDocEntryWithSourceInfo} from '../entities';
-import {DocEntryRenderable} from '../entities/renderables';
+import {EntryType, isDocEntryWithSourceInfo, PipeEntry} from '../entities';
+import {DocEntryRenderable, PipeEntryRenderable} from '../entities/renderables';
 import {
   HEADER_CLASS_NAME,
   HEADER_ENTRY_CATEGORY,
@@ -18,7 +18,7 @@ import {
 import {DocsPillRow} from './docs-pill-row';
 
 /** Component to render a header of the API page. */
-export function HeaderApi(props: {entry: DocEntryRenderable; showFullDescription?: boolean}) {
+export function HeaderApi(props: {entry: DocEntryRenderable | PipeEntryRenderable; showFullDescription?: boolean}) {
   const entry = props.entry;
 
   // TODO: This link point to the main branch.
@@ -50,6 +50,12 @@ export function HeaderApi(props: {entry: DocEntryRenderable; showFullDescription
               <a href="/reference/releases#experimental">Experimental</a>
             </div>
           )}
+
+          {entry.entryType === EntryType.Pipe && !(entry as PipeEntry).isPure && (
+            <div className={`${HEADER_ENTRY_LABEL} type-impure-pipe full`}>
+              Impure
+            </div>
+          )}
         </div>
         {sourceUrl && (
           <a

adev/shared-docs/styles/_api-item-label.scss

@@ -83,6 +83,10 @@
       --label-theme: var(--symbolic-teal);
     }
 
+    &.type-impure-pipe {
+      --label-theme: var(--symbolic-pink);
+    }
+
     &.type-ng_module {
       --label-theme: var(--symbolic-brown);
     }

adev/shared-docs/styles/_reference.scss

@@ -259,6 +259,10 @@
     }
   }
 
+  .pipe-usage {
+    padding: 1rem;
+  }
+
   // "API member card"-specific styles
   .docs-reference-member-card {
     .docs-reference-card-item {

packages/compiler-cli/src/ngtsc/annotations/src/pipe.ts

@@ -229,6 +229,7 @@ export class PipeDecoratorHandler
       isStandalone: analysis.meta.isStandalone,
       decorator: analysis.decorator,
       isExplicitlyDeferred: false,
+      isPure: analysis.meta.pure,
     });
 
     this.injectableRegistry.registerInjectable(node, {

packages/compiler-cli/src/ngtsc/docs/src/class_extractor.ts

@@ -506,6 +506,8 @@ class PipeExtractor extends ClassExtractor {
       pipeName: this.metadata.name,
       entryType: EntryType.Pipe,
       isStandalone: this.metadata.isStandalone,
+      usage: extractPipeSyntax(this.metadata, this.declaration as ts.ClassDeclaration),
+      isPure: this.metadata.isPure,
     };
   }
 }
@@ -564,3 +566,23 @@ export function extractInterface(
   const extractor = new ClassExtractor(declaration, typeChecker);
   return extractor.extract();
 }
+
+function extractPipeSyntax(metadata: PipeMeta, classDeclaration: ts.ClassDeclaration): string {
+  const transformParams = classDeclaration.members.find((member) => {
+    return (
+      ts.isMethodDeclaration(member) &&
+      member.name &&
+      ts.isIdentifier(member.name) &&
+      member.name.getText() === 'transform'
+    );
+  }) as ts.MethodDeclaration;
+
+  let paramNames = transformParams.parameters
+    // value is the first argument, it's already referenced before the pipe
+    .slice(1)
+    .map((param) => {
+      return param.name.getText();
+    });
+
+  return `{{ value_expression | ${metadata.name}${paramNames.length ? ':' + paramNames.join(':') : ''} }}`;
+}

packages/compiler-cli/src/ngtsc/docs/src/entities.ts

@@ -139,7 +139,8 @@ export interface DirectiveEntry extends ClassEntry {
 export interface PipeEntry extends ClassEntry {
   pipeName: string;
   isStandalone: boolean;
-  // TODO: add `isPure`.
+  usage: string;
+  isPure: boolean;
 }
 
 export interface FunctionSignatureMetadata extends DocEntry {

packages/compiler-cli/src/ngtsc/metadata/src/api.ts

@@ -353,6 +353,7 @@ export interface PipeMeta {
   name: string;
   nameExpr: ts.Expression | null;
   isStandalone: boolean;
+  isPure: boolean;
   decorator: ts.Decorator | null;
   isExplicitlyDeferred: boolean;
 }