[Discussion] Handling Markdown JSDoc Content

[mjbvz]

From: microsoft/vscode#27936

Problem
JSDocs often contain markdown content. TypeScript does not try to parse markdown when generating the documentation for intellisense and hovers. VSCode does try to show the documentation it gets from TypeScript as markdown. In certain edge cases, this can cause unexpected behavior:

/**
 * ```
 * @Hello
 * ```
 */
class Demo {}

In this case, @Hello is treated as a jsdoc tag instead of part of the markdown code block.

[Trace  - 3:43:51 PM] Response received: quickinfo (764). Request took 2 ms. Success: true 
Result: {
    "kind": "class",
    "kindModifiers": "",
    "start": {
        "line": 6,
        "offset": 7
    },
    "end": {
        "line": 6,
        "offset": 11
    },
    "displayString": "class Demo",
    "documentation": "```",
    "tags": [
        {
            "name": "Hello",
            "text": "```"
        }
    ]
}

Possible solutions
A few thoughts on how we could work around this:

• TypeScript parses jsdocs as markdown. Not ideal because it adds a dependency to typescript but this would be the most complete solution.

• TypeScript special cases a few markdown patterns (such as those for codeblocks) but does not try to fully parse the documentation as markdown.

• TypeScript treats any tag that is not part of the jsdoc spec as content instead of as a jsdocs tag. This is the simplest solution but I'm not sure if people are using custom jsdocs tags that this would break

// cc @mhegazy

[csvn]

This issue can be very bothersome when trying to document code that contains decorators.

/**
 * @example
 * 
 * ```
 * class ListenerExample {
 *  name = 'John Doe';
 * 
 *  @bind()
 *  onClick(e: Event) {
 *    console.log(this.name);
 *  }
 *   
 *  connectedCallback() {
 *    this.addEventListener('click', this.onClick);
 *  }
 * }
 * ```
 */
export function bind() { /* ... */ }

Is rendered as:

Right now I have to replace the @ in documentation/JSDoc comments with something else, which is not very user friendly.

[mjbvz]

Same basic issue as #39371: @ is always treated as the start of a jsdoc tag

Closing this in favor of that issue since it has more comments