feat(website): add support for type parameter documentation (#8237)

packages/website/src/DocModel/DocClass.ts

@@ -8,24 +8,29 @@ import {
 import { DocItem } from './DocItem';
 import { DocMethod } from './DocMethod';
 import { DocProperty } from './DocProperty';
-import { type TokenDocumentation, genToken } from '~/util/parse.server';
+import { type TokenDocumentation, genToken, TypeParameterData, generateTypeParamData } from '~/util/parse.server';
 
 export class DocClass extends DocItem<ApiClass> {
 	public readonly extendsTokens: TokenDocumentation[] | null;
 	public readonly implementsTokens: TokenDocumentation[][];
 	public readonly methods: DocMethod[] = [];
 	public readonly properties: DocProperty[] = [];
+	public readonly typeParameters: TypeParameterData[] = [];
 
 	public constructor(model: ApiModel, item: ApiClass) {
 		super(model, item);
 		const extendsExcerpt = item.extendsType?.excerpt;
+
 		this.extendsTokens = extendsExcerpt
 			? extendsExcerpt.spannedTokens.map((token) => genToken(this.model, token))
 			: null;
+
 		this.implementsTokens = item.implementsTypes.map((excerpt) =>
 			excerpt.excerpt.spannedTokens.map((token) => genToken(this.model, token)),
 		);
 
+		this.typeParameters = item.typeParameters.map((typeParam) => generateTypeParamData(model, typeParam));
+
 		for (const member of item.members) {
 			switch (member.kind) {
 				case ApiItemKind.Method:
@@ -47,6 +52,7 @@ export class DocClass extends DocItem<ApiClass> {
 			implementsTokens: this.implementsTokens,
 			methods: this.methods.map((method) => method.toJSON()),
 			properties: this.properties.map((prop) => prop.toJSON()),
+			typeParameters: this.typeParameters,
 		};
 	}
 }

packages/website/src/DocModel/DocFunction.ts

@@ -1,17 +1,26 @@
 import type { ApiFunction, ApiModel } from '@microsoft/api-extractor-model';
 import { DocItem } from './DocItem';
-import { type ParameterDocumentation, type TokenDocumentation, genParameter, genToken } from '~/util/parse.server';
+import {
+	type ParameterDocumentation,
+	type TokenDocumentation,
+	genParameter,
+	genToken,
+	type TypeParameterData,
+	generateTypeParamData,
+} from '~/util/parse.server';
 
 export class DocFunction extends DocItem<ApiFunction> {
 	public readonly parameters: ParameterDocumentation[];
 	public readonly returnTypeTokens: TokenDocumentation[];
 	public readonly overloadIndex: number;
+	public readonly typeParameters: TypeParameterData[] = [];
 
 	public constructor(model: ApiModel, item: ApiFunction) {
 		super(model, item);
 		this.parameters = item.parameters.map((param) => genParameter(this.model, param));
 		this.returnTypeTokens = item.returnTypeExcerpt.spannedTokens.map((token) => genToken(this.model, token));
 		this.overloadIndex = item.overloadIndex;
+		this.typeParameters = item.typeParameters.map((typeParam) => generateTypeParamData(model, typeParam));
 	}
 
 	public override toJSON() {
@@ -20,6 +29,7 @@ export class DocFunction extends DocItem<ApiFunction> {
 			parameters: this.parameters,
 			returnTypeTokens: this.returnTypeTokens,
 			overloadIndex: this.overloadIndex,
+			typeParameters: this.typeParameters,
 		};
 	}
 }

packages/website/src/DocModel/DocInterface.ts

@@ -2,12 +2,13 @@ import { DocItem } from './DocItem';
 import { DocMethodSignature } from './DocMethodSignature';
 import { DocProperty } from './DocProperty';
 import { ApiInterface, ApiItemKind, ApiMethodSignature, ApiModel, ApiPropertySignature } from '~/api-extractor.server';
-import { type TokenDocumentation, genToken } from '~/util/parse.server';
+import { type TokenDocumentation, genToken, type TypeParameterData, generateTypeParamData } from '~/util/parse.server';
 
 export class DocInterface extends DocItem<ApiInterface> {
 	public readonly extendsTokens: TokenDocumentation[][] | null;
 	public readonly methods: DocMethodSignature[] = [];
 	public readonly properties: DocProperty[] = [];
+	public readonly typeParameters: TypeParameterData[] = [];
 
 	public constructor(model: ApiModel, item: ApiInterface) {
 		super(model, item);
@@ -16,6 +17,8 @@ export class DocInterface extends DocItem<ApiInterface> {
 			excerpt.excerpt.spannedTokens.map((token) => genToken(this.model, token)),
 		);
 
+		this.typeParameters = item.typeParameters.map((typeParam) => generateTypeParamData(this.model, typeParam));
+
 		for (const member of item.members) {
 			switch (member.kind) {
 				case ApiItemKind.MethodSignature:
@@ -36,6 +39,7 @@ export class DocInterface extends DocItem<ApiInterface> {
 			extendsTokens: this.extendsTokens,
 			methods: this.methods.map((method) => method.toJSON()),
 			properties: this.properties.map((prop) => prop.toJSON()),
+			typeParameters: this.typeParameters,
 		};
 	}
 }

packages/website/src/DocModel/DocMethod.ts

@@ -1,7 +1,14 @@
 import type { ApiMethod, ApiModel } from '@microsoft/api-extractor-model';
 import { DocItem } from './DocItem';
 import { Visibility } from './Visibility';
-import { type ParameterDocumentation, type TokenDocumentation, genParameter, genToken } from '~/util/parse.server';
+import {
+	type ParameterDocumentation,
+	type TokenDocumentation,
+	genParameter,
+	genToken,
+	generateTypeParamData,
+	TypeParameterData,
+} from '~/util/parse.server';
 
 export class DocMethod extends DocItem<ApiMethod> {
 	public readonly parameters: ParameterDocumentation[];
@@ -10,6 +17,7 @@ export class DocMethod extends DocItem<ApiMethod> {
 	public readonly visibility: Visibility;
 	public readonly returnTypeTokens: TokenDocumentation[];
 	public readonly overloadIndex: number;
+	public readonly typeParameters: TypeParameterData[] = [];
 
 	public constructor(model: ApiModel, item: ApiMethod) {
 		super(model, item);
@@ -19,6 +27,7 @@ export class DocMethod extends DocItem<ApiMethod> {
 		this.visibility = item.isProtected ? Visibility.Protected : Visibility.Public;
 		this.returnTypeTokens = item.returnTypeExcerpt.spannedTokens.map((token) => genToken(this.model, token));
 		this.overloadIndex = item.overloadIndex;
+		this.typeParameters = item.typeParameters.map((typeParam) => generateTypeParamData(this.model, typeParam));
 	}
 
 	public override toJSON() {

packages/website/src/DocModel/DocMethodSignature.ts

@@ -1,12 +1,20 @@
 import type { ApiMethodSignature, ApiModel } from '@microsoft/api-extractor-model';
 import { DocItem } from './DocItem';
-import { type ParameterDocumentation, type TokenDocumentation, genParameter, genToken } from '~/util/parse.server';
+import {
+	type ParameterDocumentation,
+	type TokenDocumentation,
+	genParameter,
+	genToken,
+	generateTypeParamData,
+	type TypeParameterData,
+} from '~/util/parse.server';
 
 export class DocMethodSignature extends DocItem<ApiMethodSignature> {
 	public readonly parameters: ParameterDocumentation[];
 	public readonly optional: boolean;
 	public readonly returnTypeTokens: TokenDocumentation[];
 	public readonly overloadIndex: number;
+	public readonly typeParameters: TypeParameterData[] = [];
 
 	public constructor(model: ApiModel, item: ApiMethodSignature) {
 		super(model, item);
@@ -14,6 +22,7 @@ export class DocMethodSignature extends DocItem<ApiMethodSignature> {
 		this.optional = item.isOptional;
 		this.returnTypeTokens = item.returnTypeExcerpt.spannedTokens.map((token) => genToken(this.model, token));
 		this.overloadIndex = item.overloadIndex;
+		this.typeParameters = item.typeParameters.map((typeParam) => generateTypeParamData(this.model, typeParam));
 	}
 
 	public override toJSON() {

packages/website/src/DocModel/DocTypeAlias.ts

@@ -1,19 +1,22 @@
 import type { ApiModel, ApiTypeAlias } from '@microsoft/api-extractor-model';
 import { DocItem } from './DocItem';
-import { type TokenDocumentation, genToken } from '~/util/parse.server';
+import { type TokenDocumentation, genToken, generateTypeParamData, type TypeParameterData } from '~/util/parse.server';
 
 export class DocTypeAlias extends DocItem<ApiTypeAlias> {
 	public readonly typeTokens: TokenDocumentation[];
+	public readonly typeParameters: TypeParameterData[] = [];
 
 	public constructor(model: ApiModel, item: ApiTypeAlias) {
 		super(model, item);
 		this.typeTokens = item.typeExcerpt.spannedTokens.map((token) => genToken(model, token));
+		this.typeParameters = item.typeParameters.map((typeParam) => generateTypeParamData(this.model, typeParam));
 	}
 
 	public override toJSON() {
 		return {
 			...super.toJSON(),
 			typeTokens: this.typeTokens,
+			typeParameters: this.typeParameters,
 		};
 	}
 }

packages/website/src/components/DocContainer.tsx

@@ -1,6 +1,8 @@
 import { VscSymbolClass, VscSymbolMethod, VscSymbolEnum, VscSymbolInterface, VscSymbolVariable } from 'react-icons/vsc';
 import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
 import { vs } from 'react-syntax-highlighter/dist/cjs/styles/prism';
+import { TypeParamTable } from './TypeParamTable';
+import type { TypeParameterData } from '~/util/parse.server';
 
 export interface DocContainerProps {
 	name: string;
@@ -8,6 +10,7 @@ export interface DocContainerProps {
 	excerpt: string;
 	summary?: string | null;
 	children?: JSX.Element;
+	typeParams?: TypeParameterData[];
 }
 
 const symbolClass = 'mr-2';
@@ -20,7 +23,7 @@ const icons = {
 	TypeAlias: <VscSymbolVariable color="blue" className={symbolClass} />,
 };
 
-export function DocContainer({ name, kind, excerpt, summary, children }: DocContainerProps) {
+export function DocContainer({ name, kind, excerpt, summary, typeParams, children }: DocContainerProps) {
 	return (
 		<div className="px-10">
 			<h1 style={{ fontFamily: 'JetBrains Mono' }} className="flex items-csenter content-center">
@@ -31,6 +34,12 @@ export function DocContainer({ name, kind, excerpt, summary, children }: DocCont
 			<SyntaxHighlighter language="typescript" style={vs} codeTagProps={{ style: { fontFamily: 'JetBrains Mono' } }}>
 				{excerpt}
 			</SyntaxHighlighter>
+			{typeParams?.length ? (
+				<>
+					<h3>Type Parameters</h3>
+					<TypeParamTable data={typeParams} />
+				</>
+			) : null}
 			<h3>Summary</h3>
 			<p>{summary ?? 'No summary provided.'}</p>
 			{children}

packages/website/src/components/TypeParamTable.tsx

@@ -0,0 +1,39 @@
+import type { TypeParameterData } from '~/util/parse.server';
+import { constructHyperlinkedText } from '~/util/util';
+
+export interface TableProps {
+	data: TypeParameterData[];
+}
+
+export function TypeParamTable({ data }: TableProps) {
+	return (
+		<div className="p-10 border border-gray-200 solid rounded-md">
+			<table className="w-full text-sm text-left text-black-500 dark:text-gray-400">
+				<thead>
+					<tr>
+						<th>Name</th>
+						<th>Constraint</th>
+						<th>Optional</th>
+						<th>Default</th>
+						<th>Description</th>
+					</tr>
+				</thead>
+				<tbody>
+					{data.map((parameter) => (
+						<tr key={parameter.name} className="bg-white border-b dark:bg-gray-800 dark:border-gray-700">
+							<th className="py-4 font-normal text-gray-900 dark:text-white whitespace-nowrap">{parameter.name}</th>
+							<th>
+								<code>{constructHyperlinkedText(parameter.constraintTokens)}</code>
+							</th>
+							<th>{parameter.optional ? 'Yes' : 'No'}</th>
+							<th>
+								<code>{constructHyperlinkedText(parameter.defaultTokens)}</code>
+							</th>
+							<th>None</th>
+						</tr>
+					))}
+				</tbody>
+			</table>
+		</div>
+	);
+}

packages/website/src/components/model/Class.tsx

@@ -9,7 +9,13 @@ export interface ClassProps {
 
 export function Class({ data }: ClassProps) {
 	return (
-		<DocContainer name={data.name} kind={data.kind} excerpt={data.excerpt} summary={data.summary}>
+		<DocContainer
+			name={data.name}
+			kind={data.kind}
+			excerpt={data.excerpt}
+			summary={data.summary}
+			typeParams={data.typeParameters}
+		>
 			<>
 				{data.properties.length ? <PropertyList data={data.properties} /> : null}
 				{data.methods.length ? <MethodList data={data.methods} /> : null}

packages/website/src/components/model/Function.tsx

@@ -8,7 +8,13 @@ export interface FunctionProps {
 
 export function Function({ data }: FunctionProps) {
 	return (
-		<DocContainer name={data.name} kind={data.kind} excerpt={data.excerpt} summary={data.summary}>
+		<DocContainer
+			name={data.name}
+			kind={data.kind}
+			excerpt={data.excerpt}
+			summary={data.summary}
+			typeParams={data.typeParameters}
+		>
 			<ParameterTable data={data.parameters} />
 		</DocContainer>
 	);

packages/website/src/components/model/Interface.tsx

@@ -9,7 +9,13 @@ export interface InterfaceProps {
 
 export function Interface({ data }: InterfaceProps) {
 	return (
-		<DocContainer name={data.name} kind={data.kind} excerpt={data.excerpt} summary={data.summary}>
+		<DocContainer
+			name={data.name}
+			kind={data.kind}
+			excerpt={data.excerpt}
+			summary={data.summary}
+			typeParams={data.typeParameters}
+		>
 			<>
 				{data.properties.length ? <PropertyList data={data.properties} /> : null}
 				{data.methods.length ? <MethodList data={data.methods} /> : null}

packages/website/src/components/model/TypeAlias.tsx

@@ -7,7 +7,13 @@ export interface TypeAliasProps {
 
 export function TypeAlias({ data }: TypeAliasProps) {
 	return (
-		<DocContainer name={data.name} kind={data.kind} excerpt={data.excerpt} summary={data.summary}>
+		<DocContainer
+			name={data.name}
+			kind={data.kind}
+			excerpt={data.excerpt}
+			summary={data.summary}
+			typeParams={data.typeParameters}
+		>
 			<div>WIP</div>
 		</DocContainer>
 	);

packages/website/src/util/api-model.server.ts

@@ -19,5 +19,5 @@ export function createApiModel(data: any) {
 		tsdocConfiguration,
 	}) as ApiPackage;
 	model.addMember(apiPackage);
-	return apiPackage as unknown as ApiModel;
+	return model;
 }

packages/website/src/util/parse.server.ts

@@ -10,6 +10,7 @@ import {
 	type ApiPropertyItem,
 	type ExcerptToken,
 	type Parameter,
+	type TypeParameter,
 } from '@microsoft/api-extractor-model';
 import type { DocNode, DocParagraph, DocPlainText } from '@microsoft/tsdoc';
 
@@ -167,3 +168,22 @@ export function getMembers(pkg: ApiPackage) {
 		path: generatePath(member.getHierarchy()),
 	}));
 }
+
+export interface TypeParameterData {
+	name: string;
+	constraintTokens: TokenDocumentation[];
+	defaultTokens: TokenDocumentation[];
+	optional: boolean;
+}
+
+export function generateTypeParamData(model: ApiModel, typeParam: TypeParameter): TypeParameterData {
+	const constraintTokens = typeParam.constraintExcerpt.spannedTokens.map((token) => genToken(model, token));
+	const defaultTokens = typeParam.defaultTypeExcerpt.spannedTokens.map((token) => genToken(model, token));
+
+	return {
+		name: typeParam.name,
+		constraintTokens,
+		defaultTokens,
+		optional: typeParam.isOptional,
+	};
+}