Generate JSDoc comments from schema descriptions (including @deprecated)

[jonaslagoni]

Feature Description

Generate JSDoc comments from the description, summary, and deprecated fields in API specifications (AsyncAPI, OpenAPI, JSON Schema). Currently, descriptions are parsed from specs but not rendered as JSDoc comments in the generated TypeScript code.

Use Case

Developers using generated code benefit from:

• IDE IntelliSense: Hover documentation shows property/method descriptions
• Deprecation Warnings: IDE shows strikethrough on deprecated operations with @deprecated tag
• API Documentation: Tools like TypeDoc can generate API docs from JSDoc
• Self-Documenting Code: Generated code is more readable and maintainable
• Developer Experience: No need to reference the original spec for documentation

Proposed Implementation

1. Enable Modelina's TS_DESCRIPTION_PRESET for all generators using Modelina (payloads, models, parameters, headers)
2. Enhance renderJSDocParameters() in src/codegen/generators/typescript/utils.ts to use actual parameter descriptions instead of generic text
3. Add JSDoc to generated channel functions for publish/subscribe/request/reply operations
4. Add @deprecated JSDoc tag when operations are marked deprecated in the spec
5. Add configuration option to enable/disable JSDoc generation (default: enabled)

Technical Context

Affected Components:

• src/codegen/generators/typescript/payloads.ts - Payload model generation
• src/codegen/generators/typescript/parameters.ts - Parameter generation
• src/codegen/generators/typescript/headers.ts - Header generation
• src/codegen/generators/typescript/types.ts - Type/enum generation
• src/codegen/generators/typescript/models.ts - Complex model generation
• src/codegen/generators/typescript/utils.ts - Has renderJSDocParameters() at line 98
• src/codegen/generators/typescript/channels/types.ts - Add deprecated to RenderRegularParameters interface
• src/codegen/generators/typescript/channels/asyncapi.ts - Extract deprecation from AsyncAPI operations
• src/codegen/generators/typescript/channels/openapi.ts - Extract deprecation from OpenAPI operations
• src/codegen/generators/typescript/channels/protocols/ - All protocol generators (16+ files)
• src/codegen/modelina/presets/ - Custom Modelina presets

Similar Implementations:

• @asyncapi/modelina has TS_DESCRIPTION_PRESET (already imported in OpenAPI parameters generator at line 10-12)
• OpenAPI parameters generator uses TS_DESCRIPTION_PRESET at lines 1263-1273
• JSDoc generation pattern in src/codegen/generators/typescript/channels/protocols/nats/corePublish.ts:71-75

Current State:

• Descriptions ARE parsed from specs (confirmed in inputs/asyncapi/generators/payloads.ts and inputs/openapi/generators/parameters.ts)
• Descriptions ARE stored in schema objects
• Descriptions are NOT rendered as JSDoc in generated code
• renderJSDocParameters() generates generic text like "@param ${paramName} parameter to use in topic" instead of actual descriptions
• No deprecation support exists currently

Deprecation Sources:

• AsyncAPI: operation.deprecated() method from @asyncapi/parser
• OpenAPI: operationObj.deprecated boolean property (native to OpenAPI 2.0, 3.0, 3.1)

Acceptance Criteria

• Feature implemented as described
• Generated classes/interfaces have JSDoc with schema description
• Generated properties have JSDoc with property description
• Generated methods (marshal, unmarshal, validate) have appropriate JSDoc
• Channel functions have JSDoc with operation description and @param tags with actual descriptions
• @deprecated JSDoc tag added to generated functions when operation is marked deprecated
• Works for AsyncAPI specs (v2 and v3)
• Works for OpenAPI specs (2.0, 3.0, 3.1)
• All protocol generators support deprecation (NATS, Kafka, MQTT, AMQP, WebSocket, EventSource, HTTP)
• renderJSDocParameters() uses actual parameter descriptions from schema
• Configuration option added: jsdoc: boolean (default: true)
• Documentation added/updated
• All tests pass
• npm run prepare:pr passes

Testing Requirements

Runtime Tests (Required):

• test/runtime/typescript/test/jsdoc.spec.ts - Verify JSDoc is present in generated files
• Verify deprecated function generates correctly and compiles with strikethrough in IDE

Unit Tests (Required):

• test/codegen/generators/typescript/jsdoc.spec.ts - Test JSDoc generation logic
• Test deprecation flag propagation for each protocol

Verification:

• Generated code should include JSDoc like:

/**
 * Simple object with two properties
 */
class SimpleObject {
  /**
   * Name of the user
   */
  get name(): string | undefined { return this._name; }
}

/**
 * NATS publish operation for `user.signedup`
 * 
 * @deprecated This operation is deprecated.
 * @param message to publish
 */
function publishToUserSignedup({ message, nc, ... }) { ... }

Out of Scope

• JSDoc for languages other than TypeScript
• Generating separate documentation files (markdown, HTML)
• Complex JSDoc tags like @see, @link, @example
• Customizing JSDoc format/style
• Deprecation messages with custom text (can be added later)
• Deprecation warnings at runtime (this is compile-time/IDE only)
• Deprecation for payload models or types (separate feature if using schema-level deprecated)

Additional Context

The infrastructure for this feature largely exists:

• Modelina's TS_DESCRIPTION_PRESET handles property-level JSDoc automatically
• Schema objects already contain description fields
• Only need to enable the preset and enhance existing utilities

Spec References:

• AsyncAPI Operation Object - deprecated field
• OpenAPI Operation Object - deprecated field
• TSDoc @deprecated - Standard JSDoc/TSDoc tag

This is a high-impact, medium-complexity feature that significantly improves developer experience with generated code.