feat(website): parse tsdoc comments (#8386)

packages/website/src/components/CodeListing.tsx

@@ -1,5 +1,7 @@
 import type { ReactNode } from 'react';
+import { CommentSection } from './Comment';
 import { HyperlinkedText } from './HyperlinkedText';
+import type { DocItem } from '~/DocModel/DocItem';
 import type { TokenDocumentation } from '~/util/parse.server';
 
 export enum CodeListingSeparatorType {
@@ -9,7 +11,7 @@ export enum CodeListingSeparatorType {
 
 export interface CodeListingProps {
 	name: string;
-	summary?: string | null;
+	summary?: ReturnType<DocItem['toJSON']>['summary'];
 	typeTokens: TokenDocumentation[];
 	separator?: CodeListingSeparatorType;
 	children?: ReactNode;
@@ -34,7 +36,7 @@ export function CodeListing({
 						<HyperlinkedText tokens={typeTokens} />
 					</h4>
 				</div>
-				{summary && <p className="text-dark-100 dark:text-gray-300">{summary}</p>}
+				{summary && <CommentSection textClassName="text-dark-100 dark:text-gray-300" node={summary} />}
 				{children}
 			</div>
 		</div>

packages/website/src/components/Comment.tsx

@@ -0,0 +1,61 @@
+import Link from 'next/link';
+import type { ReactNode } from 'react';
+import { PrismAsyncLight as SyntaxHighlighter } from 'react-syntax-highlighter';
+import type { CommentNode } from '~/DocModel/comment/CommentNode';
+import type { CommentNodeContainer } from '~/DocModel/comment/CommentNodeContainer';
+import type { FencedCodeCommentNode } from '~/DocModel/comment/FencedCodeCommentNode';
+import type { LinkTagCommentNode } from '~/DocModel/comment/LinkTagCommentNode';
+import type { PlainTextCommentNode } from '~/DocModel/comment/PlainTextCommentNode';
+
+export interface RemarksBlockProps {
+	node: ReturnType<CommentNode['toJSON']>;
+	textClassName?: string | undefined;
+}
+
+export function CommentSection({ node, textClassName }: RemarksBlockProps): JSX.Element {
+	const createNode = (node: ReturnType<CommentNode['toJSON']>): ReactNode => {
+		switch (node.kind) {
+			case 'PlainText':
+				return <span>{(node as ReturnType<PlainTextCommentNode['toJSON']>).text}</span>;
+			case 'Paragraph':
+				return (
+					<p className={textClassName}>
+						{(node as ReturnType<CommentNodeContainer['toJSON']>).nodes.map((node) => createNode(node))}
+					</p>
+				);
+			case 'SoftBreak':
+				return <br />;
+			case 'LinkTag': {
+				const { codeDestination, urlDestination, text } = node as ReturnType<LinkTagCommentNode['toJSON']>;
+
+				if (codeDestination) {
+					return <Link href={codeDestination.path}>{text ?? codeDestination.name}</Link>;
+				}
+
+				if (urlDestination) {
+					return <Link href={urlDestination}>{text ?? urlDestination}</Link>;
+				}
+
+				return null;
+			}
+			case 'FencedCodeBlock': {
+				const { language, code } = node as ReturnType<FencedCodeCommentNode['toJSON']>;
+				return <SyntaxHighlighter language={language}>{code}</SyntaxHighlighter>;
+			}
+			default:
+				break;
+		}
+
+		return null;
+	};
+
+	return (
+		<div>
+			{node.kind === 'Paragraph' || node.kind === 'Section' ? (
+				<>{(node as CommentNodeContainer).nodes.map(createNode)}</>
+			) : (
+				<>{createNode(node)}</>
+			)}
+		</div>
+	);
+}

packages/website/src/components/DocContainer.tsx

@@ -3,9 +3,11 @@ import { VscListSelection, VscSymbolParameter } from 'react-icons/vsc';
 import { PrismAsyncLight as SyntaxHighlighter } from 'react-syntax-highlighter';
 import { vscDarkPlus } from 'react-syntax-highlighter/dist/cjs/styles/prism';
 import { CodeListingSeparatorType } from './CodeListing';
+import { CommentSection } from './Comment';
 import { HyperlinkedText } from './HyperlinkedText';
 import { Section } from './Section';
 import { TypeParamTable } from './TypeParamTable';
+import type { DocItem } from '~/DocModel/DocItem';
 import { generateIcon } from '~/util/icon';
 import type { TokenDocumentation, TypeParameterData } from '~/util/parse.server';
 
@@ -13,7 +15,7 @@ export interface DocContainerProps {
 	name: string;
 	kind: string;
 	excerpt: string;
-	summary?: string | null;
+	summary?: ReturnType<DocItem['toJSON']>['summary'];
 	children?: ReactNode;
 	extendsTokens?: TokenDocumentation[] | null;
 	typeParams?: TypeParameterData[];
@@ -50,7 +52,11 @@ export function DocContainer({ name, kind, excerpt, summary, typeParams, childre
 				) : null}
 				<div className="space-y-10">
 					<Section iconElement={<VscListSelection />} title="Summary" className="dark:text-white">
-						<p className="text-dark-100 dark:text-gray-300">{summary ?? 'No summary provided.'}</p>
+						{summary ? (
+							<CommentSection textClassName="text-dark-100 dark:text-gray-300" node={summary} />
+						) : (
+							<p className="text-dark-100 dark:text-gray-300">No summary provided.</p>
+						)}
 					</Section>
 					{typeParams?.length ? (
 						<Section

packages/website/src/components/MethodItem.tsx

@@ -1,4 +1,5 @@
 import { FiLink } from 'react-icons/fi';
+import { CommentSection } from './Comment';
 import { HyperlinkedText } from './HyperlinkedText';
 import { ParameterTable } from './ParameterTable';
 import type { DocMethod } from '~/DocModel/DocMethod';
@@ -43,7 +44,7 @@ export function MethodItem({ data }: MethodItemProps) {
 				</div>
 			</div>
 			<div className="mx-7 mb-5">
-				{data.summary && <p className="text-dark-100 dark:text-gray-300">{data.summary}</p>}
+				{data.summary && <CommentSection textClassName="text-dark-100 dark:text-gray-300" node={data.summary} />}
 				{data.parameters.length ? <ParameterTable data={data.parameters} /> : null}
 			</div>
 		</div>