[DRAFT] refactor(api-markdown-documenter): Simplify DocumentationNode domain

docs/infra/api-markdown-documenter/api-documentation-layout.mjs

@@ -20,7 +20,7 @@ import {
 	ReleaseTag,
 	SectionNode,
 	SpanNode,
-	transformTsdocNode,
+	transformTsdoc,
 } from "@fluid-tools/api-markdown-documenter";
 
 import { AdmonitionNode } from "./admonition-node.mjs";
@@ -181,9 +181,9 @@ export function layoutContent(apiItem, itemSpecificContent, config) {
 	const sections = [];
 
 	// Render summary comment (if any)
-	const summary = LayoutUtilities.createSummaryParagraph(apiItem, config);
+	const summary = LayoutUtilities.createSummarySection(apiItem, config);
 	if (summary !== undefined) {
-		sections.push(new SectionNode([summary]));
+		sections.push(summary);
 	}
 
 	// Render system notice (if any) that supersedes deprecation and import notices
@@ -279,13 +279,13 @@ function createDeprecationNoticeSection(apiItem, config) {
 		return undefined;
 	}
 
-	const transformedDeprecatedBlock = transformTsdocNode(deprecatedBlock, apiItem, config);
+	const transformedDeprecatedBlock = transformTsdoc(deprecatedBlock, apiItem, config);
 	if (transformedDeprecatedBlock === undefined) {
 		throw new Error("Failed to transform deprecated block.");
 	}
 
 	return new AdmonitionNode(
-		[transformedDeprecatedBlock],
+		transformedDeprecatedBlock,
 		"Warning",
 		"This API is deprecated and will be removed in a future release.",
 	);

tools/api-markdown-documenter/api-report/api-markdown-documenter.alpha.api.md

@@ -26,7 +26,6 @@ import { ApiPropertySignature } from '@microsoft/api-extractor-model';
 import { ApiTypeAlias } from '@microsoft/api-extractor-model';
 import { ApiVariable } from '@microsoft/api-extractor-model';
 import type { Data } from 'unist';
-import { DocNode } from '@microsoft/tsdoc';
 import { DocSection } from '@microsoft/tsdoc';
 import { Excerpt } from '@microsoft/api-extractor-model';
 import type { Literal } from 'unist';
@@ -158,20 +157,45 @@ export { ApiPackage }
 export type ApiSignatureLike = ApiCallSignature | ApiIndexSignature;
 
 // @public
-export class BlockQuoteNode extends DocumentationParentNodeBase {
-    constructor(children: DocumentationNode[]);
+export type BlockContent = BlockContentMap[keyof BlockContentMap];
+
+// @public
+export interface BlockContentMap {
+    // (undocumented)
+    blockquote: BlockQuoteNode;
+    // (undocumented)
+    fencedCodeBlock: FencedCodeBlockNode;
+    // (undocumented)
+    horizontalRule: HorizontalRuleNode;
+    // (undocumented)
+    lineBreak: LineBreakNode;
+    // (undocumented)
+    orderedList: OrderedListNode;
+    // (undocumented)
+    paragraph: ParagraphNode;
+    // (undocumented)
+    table: TableNode;
+    // (undocumented)
+    unorderedList: UnorderedListNode;
+}
+
+// @public
+export class BlockQuoteNode extends DocumentationParentNodeBase<PhrasingContent> {
+    constructor(children: PhrasingContent[]);
     static createFromPlainText(text: string): BlockQuoteNode;
     static readonly Empty: BlockQuoteNode;
     get singleLine(): false;
     readonly type = DocumentationNodeType.BlockQuote;
 }
 
 // @public
-export class CodeSpanNode extends DocumentationParentNodeBase<PlainTextNode> {
-    constructor(children: PlainTextNode[]);
+export class CodeSpanNode extends DocumentationLiteralNodeBase<PlainTextNode> {
+    constructor(value: PlainTextNode);
     static createFromPlainText(text: string): CodeSpanNode;
     static readonly Empty: CodeSpanNode;
-    get singleLine(): true;
+    // (undocumented)
+    get isEmpty(): boolean;
+    readonly singleLine = true;
     readonly type = DocumentationNodeType.CodeSpan;
 }
 
@@ -374,8 +398,8 @@ export namespace DocumentWriter {
 }
 
 // @public
-export class FencedCodeBlockNode extends DocumentationParentNodeBase {
-    constructor(children: DocumentationNode[], language?: string);
+export class FencedCodeBlockNode extends DocumentationParentNodeBase<PhrasingContent> {
+    constructor(children: PhrasingContent[], language?: string);
     static createFromPlainText(text: string, language?: string): FencedCodeBlockNode;
     readonly language?: string;
     get singleLine(): false;
@@ -462,12 +486,21 @@ export interface Heading {
 }
 
 // @public
-export class HeadingNode extends DocumentationParentNodeBase implements Omit<Heading, "title"> {
-    constructor(content: DocumentationNode[], id?: string);
+export class HeadingNode implements DocumentationNode<PlainTextNode>, Omit<Heading, "title"> {
+    constructor(text: PlainTextNode,
+    id?: string | undefined);
     static createFromPlainText(text: string, id?: string): HeadingNode;
     static createFromPlainTextHeading(heading: Heading): HeadingNode;
-    readonly id?: string;
-    get singleLine(): false;
+    readonly id?: string | undefined;
+    // (undocumented)
+    get isEmpty(): boolean;
+    // (undocumented)
+    readonly isLiteral = false;
+    // (undocumented)
+    readonly isParent = false;
+    readonly singleLine = true;
+    // (undocumented)
+    readonly text: PlainTextNode;
     readonly type = DocumentationNodeType.Heading;
 }
 
@@ -576,12 +609,21 @@ export interface Link {
 }
 
 // @public
-export class LinkNode extends DocumentationParentNodeBase implements Omit<Link, "text"> {
-    constructor(content: DocumentationNode[], target: UrlTarget);
+export class LinkNode implements DocumentationNode {
+    constructor(
+    text: PlainTextNode,
+    target: UrlTarget);
     static createFromPlainText(text: string, target: UrlTarget): LinkNode;
     static createFromPlainTextLink(link: Link): LinkNode;
-    get singleLine(): true;
+    // (undocumented)
+    get isEmpty(): boolean;
+    // (undocumented)
+    readonly isLiteral = false;
+    // (undocumented)
+    readonly isParent = false;
+    readonly singleLine = true;
     readonly target: UrlTarget;
+    readonly text: PlainTextNode;
     readonly type = DocumentationNodeType.Link;
 }
 
@@ -667,23 +709,40 @@ export interface MarkdownRenderers {
 export { NewlineKind }
 
 // @public
-export class OrderedListNode extends DocumentationParentNodeBase {
-    constructor(children: DocumentationNode[]);
+export class OrderedListNode extends DocumentationParentNodeBase<PhrasingContent> {
+    constructor(children: PhrasingContent[]);
     static createFromPlainTextEntries(entries: string[]): OrderedListNode;
     static readonly Empty: OrderedListNode;
     get singleLine(): false;
     readonly type = DocumentationNodeType.OrderedList;
 }
 
 // @public
-export class ParagraphNode extends DocumentationParentNodeBase {
-    constructor(children: DocumentationNode[]);
+export class ParagraphNode extends DocumentationParentNodeBase<PhrasingContent> {
+    constructor(children: PhrasingContent[]);
     static createFromPlainText(text: string): ParagraphNode;
     static readonly Empty: ParagraphNode;
     get singleLine(): false;
     readonly type = DocumentationNodeType.Paragraph;
 }
 
+// @public
+export type PhrasingContent = PhrasingContentMap[keyof PhrasingContentMap];
+
+// @public
+export interface PhrasingContentMap {
+    // (undocumented)
+    codeSpan: CodeSpanNode;
+    // (undocumented)
+    lineBreak: LineBreakNode;
+    // (undocumented)
+    link: LinkNode;
+    // (undocumented)
+    span: SpanNode;
+    // (undocumented)
+    text: PlainTextNode;
+}
+
 // @public
 export class PlainTextNode extends DocumentationLiteralNodeBase<string> {
     constructor(text: string, escaped?: boolean);
@@ -752,15 +811,17 @@ function renderNode(node: DocumentationNode, writer: DocumentWriter, context: Ma
 // @public
 function renderNodes(children: DocumentationNode[], writer: DocumentWriter, childContext: MarkdownRenderContext): void;
 
+// @public
+export type SectionContent = BlockContent | SectionNode;
+
 // @public @sealed
 export interface SectionHierarchyConfiguration extends DocumentationHierarchyConfigurationBase {
     readonly kind: HierarchyKind.Section;
 }
 
 // @public
-export class SectionNode extends DocumentationParentNodeBase {
-    constructor(children: DocumentationNode[], heading?: HeadingNode);
-    static combine(...sections: SectionNode[]): SectionNode;
+export class SectionNode extends DocumentationParentNodeBase<SectionContent> {
+    constructor(children: SectionContent[], heading?: HeadingNode);
     static readonly Empty: SectionNode;
     readonly heading?: HeadingNode;
     get singleLine(): false;
@@ -771,8 +832,11 @@ export class SectionNode extends DocumentationParentNodeBase {
 function shouldItemBeIncluded(apiItem: ApiItem, config: ApiItemTransformationConfiguration): boolean;
 
 // @public
-export class SpanNode extends DocumentationParentNodeBase {
-    constructor(children: DocumentationNode[], formatting?: TextFormatting);
+export type SpanContent = PhrasingContent | BlockContent;
+
+// @public
+export class SpanNode extends DocumentationParentNodeBase<SpanContent> {
+    constructor(children: SpanContent[], formatting?: TextFormatting);
     static createFromPlainText(text: string, formatting?: TextFormatting): SpanNode;
     static readonly Empty: SpanNode;
     readonly textFormatting?: TextFormatting;
@@ -781,7 +845,7 @@ export class SpanNode extends DocumentationParentNodeBase {
 
 // @public
 export class TableBodyCellNode extends TableCellNode {
-    constructor(children: DocumentationNode[]);
+    constructor(children: TableCellContent[]);
     static createFromPlainText(text: string): TableBodyCellNode;
     static readonly Empty: TableBodyCellNode;
 }
@@ -792,22 +856,25 @@ export class TableBodyRowNode extends TableRowNode {
     static readonly Empty: TableBodyRowNode;
 }
 
+// @public
+export type TableCellContent = PhrasingContent | BlockContent;
+
 // @public
 export enum TableCellKind {
     Body = "Body",
     Header = "Header"
 }
 
 // @public
-export abstract class TableCellNode extends DocumentationParentNodeBase {
-    protected constructor(children: DocumentationNode[], cellKind: TableCellKind);
+export abstract class TableCellNode extends DocumentationParentNodeBase<TableCellContent> {
+    protected constructor(children: TableCellContent[], cellKind: TableCellKind);
     readonly cellKind: TableCellKind;
     readonly type = DocumentationNodeType.TableCell;
 }
 
 // @public
 export class TableHeaderCellNode extends TableCellNode {
-    constructor(children: DocumentationNode[]);
+    constructor(children: TableCellContent[]);
     static createFromPlainText(text: string): TableHeaderCellNode;
     static readonly Empty: TableHeaderCellNode;
 }
@@ -880,11 +947,11 @@ export type TransformApiItemWithoutChildren<TApiItem extends ApiItem> = (apiItem
 export function transformApiModel(options: ApiItemTransformationOptions): DocumentNode[];
 
 // @public
-export function transformTsdocNode(node: DocNode, contextApiItem: ApiItem, config: ApiItemTransformationConfiguration): DocumentationNode | undefined;
+export function transformTsdoc(node: DocSection, contextApiItem: ApiItem, config: ApiItemTransformationConfiguration): BlockContent[];
 
 // @public
-export class UnorderedListNode extends DocumentationParentNodeBase {
-    constructor(children: DocumentationNode[]);
+export class UnorderedListNode extends DocumentationParentNodeBase<PhrasingContent> {
+    constructor(children: PhrasingContent[]);
     static createFromPlainTextEntries(entries: string[]): UnorderedListNode;
     static readonly Empty: UnorderedListNode;
     get singleLine(): false;