From 08d0ac73b199f5f2ba33ed392fc2c7f9bb70ce77 Mon Sep 17 00:00:00 2001 From: Matthieu Riegler Date: Mon, 12 Jan 2026 14:23:50 +0100 Subject: [PATCH] docs(docs-infra): Show API decorators docs fixes #66129 (cherry picked from commit a0564135200f0e8ebfef0953ccdb75adabd2b513) --- .../pipeline/api-gen/rendering/entities.mts | 2 +- .../rendering/entities/renderables.mts | 10 +++- .../api-gen/rendering/entities/traits.mts | 11 ++++- .../templates/decorator-reference.tsx | 46 +++++++++++++++++-- .../transforms/decorator-transforms.mts | 19 ++++++-- .../transforms/member-transforms.mts | 20 ++++++-- 6 files changed, 95 insertions(+), 13 deletions(-) diff --git a/adev/shared-docs/pipeline/api-gen/rendering/entities.mts b/adev/shared-docs/pipeline/api-gen/rendering/entities.mts index 976e1beae69..ce784693f11 100644 --- a/adev/shared-docs/pipeline/api-gen/rendering/entities.mts +++ b/adev/shared-docs/pipeline/api-gen/rendering/entities.mts @@ -126,11 +126,11 @@ export interface EnumEntry extends DocEntry { /** Documentation entity for an Angular decorator. */ export interface DecoratorEntry extends DocEntry { decoratorType: DecoratorType; + members: PropertyEntry[] | null; signatures?: { parameters: ParameterEntry[]; jsdocTags: JsDocTagEntry[]; }[]; - members: MemberEntry[]; } /** Documentation entity for an Angular directives and components. */ diff --git a/adev/shared-docs/pipeline/api-gen/rendering/entities/renderables.mts b/adev/shared-docs/pipeline/api-gen/rendering/entities/renderables.mts index f3831840784..322f7e8733e 100644 --- a/adev/shared-docs/pipeline/api-gen/rendering/entities/renderables.mts +++ b/adev/shared-docs/pipeline/api-gen/rendering/entities/renderables.mts @@ -75,7 +75,11 @@ export type PipeEntryRenderable = PipeEntry & members: MemberEntryRenderable[]; }; -export type DecoratorEntryRenderable = DecoratorEntry & DocEntryRenderable & HasRenderableToc; +export type DecoratorEntryRenderable = Omit & + DocEntryRenderable & + HasRenderableToc & { + members: PropertyEntryRenderable[]; + }; /** Documentation entity for a TypeScript enum augmented transformed content for rendering. */ export type EnumEntryRenderable = EnumEntry & @@ -116,6 +120,10 @@ export interface MemberEntryRenderable extends MemberEntry { experimental: {version: string | undefined} | undefined; } +export interface PropertyEntryRenderable extends MemberEntryRenderable { + type: string; +} + /** Sub-entry for a class method augmented transformed content for rendering. */ export type MethodEntryRenderable = MemberEntryRenderable & FunctionEntryRenderable & { diff --git a/adev/shared-docs/pipeline/api-gen/rendering/entities/traits.mts b/adev/shared-docs/pipeline/api-gen/rendering/entities/traits.mts index bdd3fccc33e..190a5697a1b 100644 --- a/adev/shared-docs/pipeline/api-gen/rendering/entities/traits.mts +++ b/adev/shared-docs/pipeline/api-gen/rendering/entities/traits.mts @@ -6,7 +6,7 @@ * found in the LICENSE file at https://angular.dev/license */ -import {JsDocTagEntry, MemberEntry, ParameterEntry} from '../entities.mjs'; +import {JsDocTagEntry, MemberEntry, ParameterEntry, PropertyEntry} from '../entities.mjs'; import { CodeLineRenderable, @@ -14,6 +14,7 @@ import { LinkEntryRenderable, MemberEntryRenderable, ParameterEntryRenderable, + PropertyEntryRenderable, } from './renderables.mjs'; /** A doc entry that has jsdoc tags. */ @@ -56,6 +57,10 @@ export interface HasMembers { members: MemberEntry[]; } +export interface HasPropertyMembers { + members: PropertyEntry[]; +} + /** A doc entry that has members groups transformed for rendering. */ export interface HasRenderableMembersGroups { membersGroups: Map; @@ -66,6 +71,10 @@ export interface HasRenderableMembers { members: MemberEntryRenderable[]; } +export interface HasRenderablePropertyMembers { + members: PropertyEntryRenderable[]; +} + /** A doc entry that has an associated JS module name. */ export interface HasModuleName { moduleName: string; diff --git a/adev/shared-docs/pipeline/api-gen/rendering/templates/decorator-reference.tsx b/adev/shared-docs/pipeline/api-gen/rendering/templates/decorator-reference.tsx index c6075edf765..95f170b75df 100644 --- a/adev/shared-docs/pipeline/api-gen/rendering/templates/decorator-reference.tsx +++ b/adev/shared-docs/pipeline/api-gen/rendering/templates/decorator-reference.tsx @@ -7,12 +7,45 @@ */ import {h} from 'preact'; +import {DecoratorEntryRenderable, PropertyEntryRenderable} from '../entities/renderables.mjs'; +import { + API_REFERENCE_CONTAINER, + REFERENCE_MEMBER_CARD, + REFERENCE_MEMBER_CARD_BODY, + REFERENCE_MEMBER_CARD_HEADER, + REFERENCE_MEMBER_CARD_ITEM, + REFERENCE_MEMBERS, +} from '../styling/css-classes.mjs'; +import {CodeSymbol} from './code-symbols'; import {HeaderApi} from './header-api'; +import {RawHtml} from './raw-html'; +import {SectionApi} from './section-api'; import {SectionDescription} from './section-description'; import {SectionUsageNotes} from './section-usage-notes'; -import {SectionApi} from './section-api'; -import {API_REFERENCE_CONTAINER} from '../styling/css-classes.mjs'; -import {DecoratorEntryRenderable} from '../entities/renderables.mjs'; + +export const signatureCard = ( + name: string, + member: PropertyEntryRenderable, + opts: {id: string}, +) => { + return ( +
+
+

{name}

+
+ +
+
+
+
+

+ +

+
+
+
+ ); +}; /** Component to render a decorator API reference document. */ export function DecoratorReference(entry: DecoratorEntryRenderable) { @@ -20,6 +53,13 @@ export function DecoratorReference(entry: DecoratorEntryRenderable) {
+
+ {entry.members.map((member, index) => + signatureCard(member.name, member, { + id: `${member.name}_${index}`, + }), + )} +
diff --git a/adev/shared-docs/pipeline/api-gen/rendering/transforms/decorator-transforms.mts b/adev/shared-docs/pipeline/api-gen/rendering/transforms/decorator-transforms.mts index c8553c2f455..3f35fdd88f0 100644 --- a/adev/shared-docs/pipeline/api-gen/rendering/transforms/decorator-transforms.mts +++ b/adev/shared-docs/pipeline/api-gen/rendering/transforms/decorator-transforms.mts @@ -16,6 +16,7 @@ import { addHtmlUsageNotes, setEntryFlags, } from './jsdoc-transforms.mjs'; +import {addRenderablePropertyMembers} from './member-transforms.mjs'; import {addModuleName} from './module-name.mjs'; import {addRepo} from './repo.mjs'; @@ -25,14 +26,24 @@ export async function getDecoratorRenderable( moduleName: string, repo: string, ): Promise { + const decoratorEntryWithMembers = { + ...decoratorEntry, + members: decoratorEntry.members ?? [], + }; + return setEntryFlags( await addRenderableCodeToc( - addHtmlAdditionalLinks( - addHtmlUsageNotes( - addHtmlJsDocTagComments( - addHtmlDescription(addRepo(addModuleName(decoratorEntry, moduleName), repo)), + await addRenderablePropertyMembers( + addHtmlAdditionalLinks( + addHtmlUsageNotes( + addHtmlJsDocTagComments( + addHtmlDescription( + addRepo(addModuleName(decoratorEntryWithMembers, moduleName), repo), + ), + ), ), ), + decoratorEntry.name, ), ), ) as DecoratorEntryRenderable; diff --git a/adev/shared-docs/pipeline/api-gen/rendering/transforms/member-transforms.mts b/adev/shared-docs/pipeline/api-gen/rendering/transforms/member-transforms.mts index 41912dddfc7..d87045e41b3 100644 --- a/adev/shared-docs/pipeline/api-gen/rendering/transforms/member-transforms.mts +++ b/adev/shared-docs/pipeline/api-gen/rendering/transforms/member-transforms.mts @@ -10,7 +10,14 @@ import {MemberEntry, MemberTags, MemberType, type DocEntry} from '../entities.mj import {isHiddenEntry} from '../entities/categorization.mjs'; import type {MemberEntryRenderable} from '../entities/renderables.mjs'; -import {HasMembers, HasModuleName, HasRenderableMembers, HasRepo} from '../entities/traits.mjs'; +import { + HasMembers, + HasModuleName, + HasPropertyMembers, + HasRenderableMembers, + HasRenderablePropertyMembers, + HasRepo, +} from '../entities/traits.mjs'; import {addRenderableCodeToc} from './code-transforms.mjs'; import { @@ -85,8 +92,7 @@ export async function addRenderableMembers { const members = ( await Promise.all( - // TODO: remove `?? []` when components repo is updated to include members array on type aliases. - (entry.members ?? []) + entry.members .filter((member) => !isHiddenEntry(member)) .map((member) => { if (member.memberType === MemberType.Interface) { @@ -112,3 +118,11 @@ export async function addRenderableMembers(entry: T, parentName: string): Promise { + return { + ...((await addRenderableMembers(entry, parentName)) as T & HasRenderablePropertyMembers), + }; +}