[Emitter Framework] Emit TypeSpec docs as JSDoc in TypeScript components (microsoft#7409)

Plumbing TypeSpec docs all the way through alloy to emit JSDocs based on
TypeSpec docs

Author: joheredi

.chronus/changes/joheredi-ef-plumb-docs-2025-4-21-1-15-10.md

@@ -0,0 +1,8 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/emitter-framework"
+  - "@typespec/http-client-js"
+---
+
+Emit TypeSpec comments as JSDoc in TypeScript components

packages/emitter-framework/src/typescript/components/enum-declaration.tsx

@@ -28,13 +28,22 @@ export function EnumDeclaration(props: EnumDeclarationProps) {
   const refkeys = declarationRefkeys(props.refkey, props.type);
   const name = props.name ?? ts.useTSNamePolicy().getName(props.type.name!, "enum");
   const members = Array.from(type.members.entries());
+  const doc = props.doc ?? $.type.getDoc(type);
 
   return (
-    <ts.EnumDeclaration name={name} refkey={refkeys} default={props.default} export={props.export}>
+    <ts.EnumDeclaration
+      doc={doc}
+      name={name}
+      refkey={refkeys}
+      default={props.default}
+      export={props.export}
+    >
       <ay.For each={members} joiner={",\n"}>
         {([key, value]) => {
+          const memberDoc = $.type.getDoc(value);
           return (
             <EnumMember
+              doc={memberDoc}
               type={value}
               refkey={
                 $.union.is(props.type) ? efRefkey(props.type.variants.get(key)) : efRefkey(value)
@@ -49,12 +58,14 @@ export function EnumDeclaration(props: EnumDeclarationProps) {
 
 export interface EnumMemberProps {
   type: TspEnumMember;
+  doc?: ay.Children;
   refkey?: ay.Refkey;
 }
 
 export function EnumMember(props: EnumMemberProps) {
   return (
     <ts.EnumMember
+      doc={props.doc}
       name={props.type.name}
       jsValue={props.type.value ?? props.type.name}
       refkey={props.refkey}

packages/emitter-framework/src/typescript/components/function-declaration.tsx

@@ -1,5 +1,6 @@
 import * as ts from "@alloy-js/typescript";
 import { Model, Operation } from "@typespec/compiler";
+import { useTsp } from "../../core/index.js";
 import { buildParameterDescriptors, getReturnType } from "../utils/operation.js";
 import { declarationRefkeys } from "../utils/refkey.js";
 import { TypeExpression } from "./type-expression.js";
@@ -21,6 +22,8 @@ export type FunctionDeclarationProps =
  * provided will take precedence.
  */
 export function FunctionDeclaration(props: FunctionDeclarationProps) {
+  const { $ } = useTsp();
+
   if (!isTypedFunctionDeclarationProps(props)) {
     return <ts.FunctionDeclaration {...props} />;
   }
@@ -40,17 +43,19 @@ export function FunctionDeclaration(props: FunctionDeclarationProps) {
     params: props.parameters,
     mode: props.parametersMode,
   });
+  const doc = props.doc ?? $.type.getDoc(props.type);
   return (
     <ts.FunctionDeclaration
+      doc={doc}
       refkey={refkeys}
       name={name}
       async={props.async}
       default={props.default}
       export={props.export}
       kind={props.kind}
       returnType={returnType}
+      parameters={allParameters}
     >
-      <ts.FunctionDeclaration.Parameters parameters={allParameters} />
       {props.children}
     </ts.FunctionDeclaration>
   );

packages/emitter-framework/src/typescript/components/interface-declaration.tsx

@@ -45,9 +45,11 @@ export function InterfaceDeclaration(props: InterfaceDeclarationProps) {
   const refkeys = declarationRefkeys(props.refkey, props.type);
 
   const extendsType = props.extends ?? getExtendsType($, props.type);
+  const doc = props.doc ?? $.type.getDoc(props.type);
 
   return (
     <ts.InterfaceDeclaration
+      doc={doc}
       default={props.default}
       export={props.export}
       kind={props.kind}

packages/emitter-framework/src/typescript/components/interface-member.tsx

@@ -1,3 +1,4 @@
+import { Children } from "@alloy-js/core";
 import * as ts from "@alloy-js/typescript";
 import { isNeverType, ModelProperty, Operation } from "@typespec/compiler";
 import { getHttpPart } from "@typespec/http";
@@ -7,13 +8,15 @@ import { TypeExpression } from "./type-expression.js";
 
 export interface InterfaceMemberProps {
   type: ModelProperty | Operation;
+  doc?: Children;
   optional?: boolean;
 }
 
 export function InterfaceMember(props: InterfaceMemberProps) {
   const { $ } = useTsp();
   const namer = ts.useTSNamePolicy();
   const name = namer.getName(props.type.name, "object-member-getter");
+  const doc = props.doc ?? $.type.getDoc(props.type);
 
   if ($.modelProperty.is(props.type)) {
     if (isNeverType(props.type.type)) {
@@ -28,6 +31,7 @@ export function InterfaceMember(props: InterfaceMemberProps) {
 
     return (
       <ts.InterfaceMember
+        doc={doc}
         name={name}
         optional={props.optional ?? props.type.optional}
         type={<TypeExpression type={unpackedType} />}

packages/emitter-framework/src/typescript/components/interface-method.tsx

@@ -1,12 +1,14 @@
-import { splitProps } from "@alloy-js/core/jsx-runtime";
+import { Children, splitProps } from "@alloy-js/core";
 import * as ts from "@alloy-js/typescript";
 import { Operation } from "@typespec/compiler";
+import { useTsp } from "../../core/index.js";
 import { buildParameterDescriptors, getReturnType } from "../utils/operation.js";
 import { TypeExpression } from "./type-expression.jsx";
 
 export interface InterfaceMethodPropsWithType extends Omit<ts.InterfaceMethodProps, "name"> {
   type: Operation;
   name?: string;
+  doc?: Children;
   parametersMode?: "prepend" | "append" | "replace";
 }
 
@@ -18,6 +20,7 @@ export type InterfaceMethodProps = InterfaceMethodPropsWithType | ts.InterfaceMe
  * provided will take precedence.
  */
 export function InterfaceMethod(props: Readonly<InterfaceMethodProps>) {
+  const { $ } = useTsp();
   const isTypeSpecTyped = "type" in props;
   if (!isTypeSpecTyped) {
     return <ts.InterfaceMethod {...props} />;
@@ -36,13 +39,16 @@ export function InterfaceMethod(props: Readonly<InterfaceMethodProps>) {
     mode: props.parametersMode,
   });
 
+  const doc = props.doc ?? $.type.getDoc(props.type);
+
   return (
     <ts.InterfaceMethod
       {...forwardProps}
       {...updateProps}
       name={name}
       returnType={returnType}
       parameters={allParameters}
+      doc={doc}
     />
   );
 }

packages/emitter-framework/src/typescript/components/type-alias-declaration.tsx

@@ -30,11 +30,12 @@ export function TypeAliasDeclaration(props: TypeAliasDeclarationProps) {
     reportDiagnostic($.program, { code: "type-declaration-missing-name", target: props.type });
   }
 
+  const doc = props.doc ?? $.type.getDoc(props.type);
   const refkeys = declarationRefkeys(props.refkey, props.name);
 
   const name = ts.useTSNamePolicy().getName(originalName, "type");
   return (
-    <ts.TypeDeclaration {...props} name={name} refkey={refkeys}>
+    <ts.TypeDeclaration doc={doc} {...props} name={name} refkey={refkeys}>
       <TypeExpression type={props.type} noReference />
       {props.children}
     </ts.TypeDeclaration>

packages/emitter-framework/src/typescript/components/type-declaration.tsx

@@ -1,5 +1,6 @@
 import * as ts from "@alloy-js/typescript";
 import { Type } from "@typespec/compiler";
+import { useTsp } from "../../core/index.js";
 import { declarationRefkeys } from "../utils/refkey.js";
 import { EnumDeclaration } from "./enum-declaration.js";
 import { InterfaceDeclaration } from "./interface-declaration.jsx";
@@ -14,9 +15,9 @@ export interface TypeDeclarationProps extends Omit<ts.TypeDeclarationProps, "nam
 export type WithRequired<T, K extends keyof T> = T & { [P in K]-?: T[P] };
 
 export function TypeDeclaration(props: TypeDeclarationProps) {
+  const { $ } = useTsp();
   if (!props.type) {
     const refkeys = declarationRefkeys(props.refkey, props.name);
-
     return (
       <ts.TypeDeclaration
         {...(props as WithRequired<ts.TypeDeclarationProps, "name">)}
@@ -26,16 +27,17 @@ export function TypeDeclaration(props: TypeDeclarationProps) {
   }
 
   const { type, ...restProps } = props;
+  const doc = props.doc ?? $.type.getDoc(type);
   switch (type.kind) {
     case "Model":
-      return <InterfaceDeclaration type={type} {...restProps} />;
+      return <InterfaceDeclaration doc={doc} type={type} {...restProps} />;
     case "Union":
-      return <UnionDeclaration type={type} {...restProps} />;
+      return <UnionDeclaration doc={doc} type={type} {...restProps} />;
     case "Enum":
-      return <EnumDeclaration type={type} {...restProps} />;
+      return <EnumDeclaration doc={doc} type={type} {...restProps} />;
     case "Scalar":
-      return <TypeAliasDeclaration type={type} {...restProps} />;
+      return <TypeAliasDeclaration doc={doc} type={type} {...restProps} />;
     case "Operation":
-      return <TypeAliasDeclaration type={type} {...restProps} />;
+      return <TypeAliasDeclaration doc={doc} type={type} {...restProps} />;
   }
 }

packages/emitter-framework/src/typescript/components/union-declaration.tsx

@@ -1,3 +1,4 @@
+import { Children } from "@alloy-js/core";
 import * as ts from "@alloy-js/typescript";
 import { Enum, Union } from "@typespec/compiler";
 import { useTsp } from "../../core/context/tsp-context.js";
@@ -7,6 +8,7 @@ import { UnionExpression } from "./union-expression.js";
 
 export interface TypedUnionDeclarationProps extends Omit<ts.TypeDeclarationProps, "name"> {
   type: Union | Enum;
+  doc?: Children;
   name?: string;
 }
 
@@ -29,8 +31,9 @@ export function UnionDeclaration(props: UnionDeclarationProps) {
 
   const name = ts.useTSNamePolicy().getName(originalName!, "type");
 
+  const doc = props.doc ?? $.type.getDoc(type);
   return (
-    <ts.TypeDeclaration {...props} name={name} refkey={refkeys}>
+    <ts.TypeDeclaration doc={doc} {...props} name={name} refkey={refkeys}>
       <UnionExpression type={type}>{coreProps.children}</UnionExpression>
     </ts.TypeDeclaration>
   );

packages/emitter-framework/src/typescript/utils/operation.ts

@@ -47,10 +47,13 @@ export function buildParameterDescriptors(
 }
 
 export function buildParameterDescriptor(modelProperty: ModelProperty): ts.ParameterDescriptor {
+  const { $ } = useTsp();
   const namePolicy = ts.useTSNamePolicy();
   const paramName = namePolicy.getName(modelProperty.name, "parameter");
   const isOptional = modelProperty.optional || modelProperty.defaultValue !== undefined;
+  const doc = $.type.getDoc(modelProperty);
   return {
+    doc,
     name: paramName,
     refkey: efRefkey(modelProperty),
     optional: isOptional,