feat: generate JSDoc comments from schema descriptions (including @deprecated)

src/codegen/generators/typescript/channels/openapi.ts

@@ -217,6 +217,10 @@ function processOperation(
     return undefined;
   }
 
+  // Extract operation metadata for JSDoc
+  const description = operation.description ?? operation.summary;
+  const deprecated = operation.deprecated === true;
+
   // Generate the HTTP client function
   return renderHttpFetchClient({
     subName: pascalCase(operationId),
@@ -236,7 +240,9 @@ function processOperation(
     channelParameters: parameterModel?.model as
       | ConstrainedObjectModel
       | undefined,
-    includesStatusCodes: replyIncludesStatusCodes
+    includesStatusCodes: replyIncludesStatusCodes,
+    description,
+    deprecated
   });
 }
 

src/codegen/generators/typescript/channels/protocols/amqp/index.ts

@@ -6,7 +6,11 @@ import {
   ChannelFunctionTypes,
   TypeScriptChannelsGeneratorContext
 } from '../../types';
-import {findNameFromOperation, findOperationId} from '../../../../../utils';
+import {
+  findNameFromOperation,
+  findOperationId,
+  getOperationMetadata
+} from '../../../../../utils';
 import {getMessageTypeAndModule} from '../../utils';
 import {
   shouldRenderFunctionType,
@@ -113,11 +117,15 @@ async function generateForOperations(
         `Could not find message type for channel typescript generator for AMQP`
       );
     }
+    // Extract operation metadata for JSDoc
+    const {description, deprecated} = getOperationMetadata(operation);
     const updatedContext = {
       ...amqpContext,
       messageType,
       messageModule,
-      subName: findNameFromOperation(operation, channel)
+      subName: findNameFromOperation(operation, channel),
+      description,
+      deprecated
     };
 
     renders.push(

src/codegen/generators/typescript/channels/protocols/amqp/publishExchange.ts

@@ -3,6 +3,7 @@ import {ChannelFunctionTypes} from '../..';
 import {SingleFunctionRenderType} from '../../../../../types';
 import {pascalCase} from '../../../utils';
 import {RenderRegularParameters} from '../../types';
+import {renderChannelJSDoc} from '../../utils';
 
 export function renderPublishExchange({
   topic,
@@ -12,7 +13,9 @@ export function renderPublishExchange({
   channelHeaders,
   subName = pascalCase(topic),
   functionName = `publishTo${subName}Exchange`,
-  additionalProperties
+  additionalProperties,
+  description,
+  deprecated
 }: RenderRegularParameters<{
   exchange: string | undefined;
 }>): SingleFunctionRenderType {
@@ -83,11 +86,16 @@ channel.publish(exchange, routingKey, Buffer.from(dataToSend), publishOptions);`
     }
   ];
 
-  const code = `/**
- * AMQP publish operation for exchange \`${topic}\`
- *
- ${functionParameters.map((param) => param.jsDoc).join('\n')}
- */
+  const jsDoc = renderChannelJSDoc({
+    description,
+    deprecated,
+    fallbackDescription: `AMQP publish operation for exchange \`${topic}\``,
+    parameters: functionParameters.map((param) => ({
+      jsDoc: param.jsDoc
+    }))
+  });
+
+  const code = `${jsDoc}
 function ${functionName}({
   ${functionParameters.map((param) => param.parameter).join(', \n  ')}
 }: {

src/codegen/generators/typescript/channels/protocols/amqp/publishQueue.ts

@@ -3,6 +3,7 @@ import {ChannelFunctionTypes} from '../..';
 import {SingleFunctionRenderType} from '../../../../../types';
 import {pascalCase} from '../../../utils';
 import {RenderRegularParameters} from '../../types';
+import {renderChannelJSDoc} from '../../utils';
 
 export function renderPublishQueue({
   topic,
@@ -11,7 +12,9 @@ export function renderPublishQueue({
   channelParameters,
   channelHeaders,
   subName = pascalCase(topic),
-  functionName = `publishTo${subName}Queue`
+  functionName = `publishTo${subName}Queue`,
+  description,
+  deprecated
 }: RenderRegularParameters): SingleFunctionRenderType {
   const addressToUse = channelParameters
     ? `parameters.getChannelWithParameters('${topic}')`
@@ -80,11 +83,16 @@ channel.sendToQueue(queue, Buffer.from(dataToSend), publishOptions);`;
     }
   ];
 
-  const code = `/**
- * AMQP publish operation for queue \`${topic}\`
- *
- ${functionParameters.map((param) => param.jsDoc).join('\n')}
- */
+  const jsDoc = renderChannelJSDoc({
+    description,
+    deprecated,
+    fallbackDescription: `AMQP publish operation for queue \`${topic}\``,
+    parameters: functionParameters.map((param) => ({
+      jsDoc: param.jsDoc
+    }))
+  });
+
+  const code = `${jsDoc}
 function ${functionName}({
   ${functionParameters.map((param) => param.parameter).join(', \n  ')}
 }: {

src/codegen/generators/typescript/channels/protocols/amqp/subscribeQueue.ts

@@ -2,7 +2,7 @@ import {ChannelFunctionTypes} from '../..';
 import {SingleFunctionRenderType} from '../../../../../types';
 import {pascalCase} from '../../../utils';
 import {RenderRegularParameters} from '../../types';
-import {getValidationFunctions} from '../../utils';
+import {getValidationFunctions, renderChannelJSDoc} from '../../utils';
 
 export function renderSubscribeQueue({
   topic,
@@ -12,7 +12,9 @@ export function renderSubscribeQueue({
   channelHeaders,
   subName = pascalCase(topic),
   functionName = `subscribeTo${subName}Queue`,
-  payloadGenerator
+  payloadGenerator,
+  description,
+  deprecated
 }: RenderRegularParameters): SingleFunctionRenderType {
   const includeValidation = payloadGenerator.generator.includeValidation;
   const addressToUse = channelParameters
@@ -116,11 +118,16 @@ channel.consume(queue, (msg) => {
     }
   ];
 
-  const code = `/**
- * AMQP subscribe operation for queue \`${topic}\`
- *
- ${functionParameters.map((param) => param.jsDoc).join('\n')}
- */
+  const jsDoc = renderChannelJSDoc({
+    description,
+    deprecated,
+    fallbackDescription: `AMQP subscribe operation for queue \`${topic}\``,
+    parameters: functionParameters.map((param) => ({
+      jsDoc: param.jsDoc
+    }))
+  });
+
+  const code = `${jsDoc}
 function ${functionName}({
   ${functionParameters.map((param) => param.parameter).join(', \n  ')}
 }: {

src/codegen/generators/typescript/channels/protocols/eventsource/express.ts

@@ -3,6 +3,7 @@ import {ChannelFunctionTypes} from '../..';
 import {SingleFunctionRenderType} from '../../../../../types';
 import {findRegexFromChannel, pascalCase} from '../../../utils';
 import {RenderRegularParameters} from '../../types';
+import {renderChannelJSDoc} from '../../utils';
 
 export function renderExpress({
   topic,
@@ -11,7 +12,9 @@ export function renderExpress({
   channelParameters,
   channelHeaders,
   subName = pascalCase(topic),
-  functionName = `register${subName}`
+  functionName = `register${subName}`,
+  description,
+  deprecated
 }: RenderRegularParameters): SingleFunctionRenderType {
   let addressToUse = topic.replace(/{([^}]+)}/g, ':$1');
   addressToUse = addressToUse.startsWith('/')
@@ -64,7 +67,17 @@ export function renderExpress({
     }
   ];
 
-  const code = `function ${functionName}({
+  const jsDoc = renderChannelJSDoc({
+    description,
+    deprecated,
+    fallbackDescription: `Register EventSource endpoint for \`${topic}\``,
+    parameters: functionParameters.map((param) => ({
+      jsDoc: param.jsDoc
+    }))
+  });
+
+  const code = `${jsDoc}
+function ${functionName}({
   ${functionParameters.map((param) => param.parameter).join(', \n  ')}
 }: {
   ${functionParameters.map((param) => param.parameterType).join(', \n  ')}

src/codegen/generators/typescript/channels/protocols/eventsource/fetch.ts

@@ -6,7 +6,7 @@ import {
   defaultTypeScriptChannelsGenerator,
   RenderRegularParameters
 } from '../../types';
-import {getValidationFunctions} from '../../utils';
+import {getValidationFunctions, renderChannelJSDoc} from '../../utils';
 
 export function renderFetch({
   topic,
@@ -19,7 +19,9 @@ export function renderFetch({
   additionalProperties = {
     fetchDependency: defaultTypeScriptChannelsGenerator.eventSourceDependency
   },
-  payloadGenerator
+  payloadGenerator,
+  description,
+  deprecated
 }: RenderRegularParameters<{
   fetchDependency: string;
 }>): SingleFunctionRenderType {
@@ -75,12 +77,21 @@ export function renderFetch({
     }
   ];
 
-  const code = `/**
- * Event source fetch for \`${topic}\`
- *
- ${functionParameters.map((param) => param.jsDoc).join('\n')}
- * @returns A cleanup function to abort the connection
- */
+  const jsDoc = renderChannelJSDoc({
+    description,
+    deprecated,
+    fallbackDescription: `Event source fetch for \`${topic}\``,
+    parameters: [
+      ...functionParameters.map((param) => ({
+        jsDoc: param.jsDoc
+      })),
+      {
+        jsDoc: ' * @returns A cleanup function to abort the connection'
+      }
+    ]
+  });
+
+  const code = `${jsDoc}
 function ${functionName}({
   ${functionParameters.map((param) => param.parameter).join(', \n  ')}
 }: {

src/codegen/generators/typescript/channels/protocols/eventsource/index.ts

@@ -6,7 +6,11 @@ import {
   ChannelFunctionTypes,
   TypeScriptChannelsGeneratorContext
 } from '../../types';
-import {findNameFromOperation, findOperationId} from '../../../../../utils';
+import {
+  findNameFromOperation,
+  findOperationId,
+  getOperationMetadata
+} from '../../../../../utils';
 import {getMessageTypeAndModule} from '../../utils';
 import {
   shouldRenderFunctionType,
@@ -112,11 +116,15 @@ async function generateForOperations(
         `Could not find message type for channel typescript generator for EventSource`
       );
     }
+    // Extract operation metadata for JSDoc
+    const {description, deprecated} = getOperationMetadata(operation);
     const updatedContext = {
       ...eventSourceContext,
       messageType,
       messageModule,
-      subName: findNameFromOperation(operation, channel)
+      subName: findNameFromOperation(operation, channel),
+      description,
+      deprecated
     };
 
     renders.push(

src/codegen/generators/typescript/channels/protocols/http/client.ts

@@ -5,6 +5,7 @@
 import {HttpRenderType} from '../../../../../types';
 import {pascalCase} from '../../../utils';
 import {ChannelFunctionTypes, RenderHttpParameters} from '../../types';
+import {renderChannelJSDoc} from '../../utils';
 
 /**
  * Renders an HTTP fetch client function for a specific API operation.
@@ -20,7 +21,9 @@ export function renderHttpFetchClient({
   servers = [],
   subName = pascalCase(requestTopic),
   functionName = `${method.toLowerCase()}${subName}`,
-  includesStatusCodes = false
+  includesStatusCodes = false,
+  description,
+  deprecated
 }: RenderHttpParameters): HttpRenderType {
   const messageType = requestMessageModule
     ? `${requestMessageModule}.${requestMessageType}`
@@ -43,6 +46,13 @@ export function renderHttpFetchClient({
     method
   );
 
+  // Generate JSDoc for the function
+  const jsDoc = renderChannelJSDoc({
+    description,
+    deprecated,
+    fallbackDescription: `HTTP ${method} request to ${requestTopic}`
+  });
+
   // Generate the function implementation
   const functionCode = generateFunctionImplementation({
     functionName,
@@ -55,7 +65,8 @@ export function renderHttpFetchClient({
     hasParameters,
     method,
     servers,
-    includesStatusCodes
+    includesStatusCodes,
+    jsDoc
   });
 
   const code = `${contextInterface}
@@ -122,6 +133,7 @@ function generateFunctionImplementation(params: {
   method: string;
   servers: string[];
   includesStatusCodes: boolean;
+  jsDoc: string;
 }): string {
   const {
     functionName,
@@ -134,7 +146,8 @@ function generateFunctionImplementation(params: {
     hasParameters,
     method,
     servers,
-    includesStatusCodes
+    includesStatusCodes,
+    jsDoc
   } = params;
 
   const defaultServer = servers[0] ?? "'localhost:3000'";
@@ -170,7 +183,8 @@ function generateFunctionImplementation(params: {
   // Generate default context for optional context parameter
   const contextDefault = !hasBody && !hasParameters ? ' = {}' : '';
 
-  return `async function ${functionName}(context: ${contextInterfaceName}${contextDefault}): Promise<HttpClientResponse<${replyType}>> {
+  return `${jsDoc}
+async function ${functionName}(context: ${contextInterfaceName}${contextDefault}): Promise<HttpClientResponse<${replyType}>> {
   // Apply defaults
   const config = {
     path: '${requestTopic}',

src/codegen/generators/typescript/channels/protocols/http/index.ts

@@ -7,7 +7,8 @@ import {
 import {
   findNameFromOperation,
   findOperationId,
-  findReplyId
+  findReplyId,
+  getOperationMetadata
 } from '../../../../../utils';
 import {getMessageTypeAndModule} from '../../utils';
 import {
@@ -149,6 +150,7 @@ function generateForOperations(
             `Could not find reply message type for channel typescript generator for HTTP`
           );
         }
+        const {description, deprecated} = getOperationMetadata(operation);
         renders.push(
           renderHttpFetchClient({
             subName: findNameFromOperation(operation, channel),
@@ -160,7 +162,9 @@ function generateForOperations(
             method: httpMethod.toUpperCase(),
             channelParameters:
               parameters !== undefined ? parameters : undefined,
-            includesStatusCodes: replyIncludesStatusCodes
+            includesStatusCodes: replyIncludesStatusCodes,
+            description,
+            deprecated
           })
         );
       }