add configuration option for JSDoc comment format in code generation

[dragonfleas]

Description

When using the AWS SDK v3 in VSCode, there's an ongoing issue with JSDoc comments containing HTML tags (particularly <p> tags) not rendering properly in IntelliSense. This affects developer experience as many type definitions become difficult to read or are stripped entirely from the IDE. This buggy behavior has been erroneously ignored for years.

The issue stems from VSCode's handling of HTML tags in JSDoc comments (see microsoft/vscode#113959), where content between <p> tags (as well as some other tags) is stripped from the IntelliSense display. The ideal solution would be for the plaintext equivalent of the content between HTML tags to remain, but this isn't the behavior implemented by the VSCode team. This is particularly problematic for AWS SDK v3 users since many type definitions use these tags in their documentation.

Proposed solution

Add a configuration option in smithy-typescript's code generation that allows developers to specify the format of generated JSDoc comments. This could include options like:

• plaintext: Generate comments without any HTML/markdown formatting
• markdown: Generate comments using pure markdown
• markdown-html: Current behavior (using HTML tags with CommonMark)

Example configuration in smithy-build.json:

{
    "plugins": {
        "typescript-client-codegen": {
            "package": "@aws-sdk/example",
            "packageVersion": "1.0.0",
            "jsdocFormat": "plaintext"  // Note: Options are "plaintext", "markdown", or "html"
        }
    }
}

Hacky workaround potential:

If there isn't interest in this feature from the smithy team, or if there is community interest in a workaround in the meantime, I could maintain a regularly updated fork of aws-sdk-js-v3 that converts all HTML to pure markdown. There are several libraries that can easily accomplish this, making it potentially trivial to target comments in a parser and sanitize them in place.

Relevant issues:

• Use markdown in code comments instead of HTML aws/aws-sdk-js-v3#1875 - Original issue
• CommonMark compliant HTML block inside <p> tag is removed by JSDoc Intellisense microsoft/vscode#113959
• Some HTML-formatted text is completely removed from JSDoc Intellisense microsoft/vscode#110945
• Support rendering raw HTML tags that appear in a MarkdownString microsoft/vscode#40607 - Note: While this issue is closed, VSCode has only added API support for the potential rendering of HTML inside Markdown objects in VSCode's API.
• JSDoc Intellisense continues to completely remove HTML tag contents microsoft/vscode#146521 - This is where VSCode's team confirmed this behavior is by design. They do not allow HTML tags inside of markdown and this is unlikely to change, as they've been rejecting attempts to implement it. Their stated reasoning is to maintain control within the editor, regardless of whether this conflicts with JSDoc specifications.

---

In conclusion:

Currently, using aws-sdk-v3-js requires keeping an AWS API reference specification window consistently open and manually copying/pasting various member types, rather than being able to understand simple things through IntelliSense. For example, determining whether an arn field on an object refers to a parent ARN or the ARN of the resource being worked with becomes extremely frustrating. While ctrl-clicking into the model.d.ts is an option, it's even less helpful than consulting the documentation directly, and neither solution is ideal.