lib.dom.d.ts should escape html elements in jsdoc comments

[mjbvz]

lib Update Request

Configuration Check

My compilation target is ES2020 and my lib is the default.

Missing / Incorrect Definition

For html elements such as HTMLScriptElement, the JSDoc includes <script>. This causes VS Code to drop the entire body of the comment

Sample Code

const a: HTMLScriptElement // hover over HTMLScriptElement

Proposal

These JSDoc comments should escape any html in the comments. I suggest using markdown inline code instead:

/** HTML `<script>` elements expose the HTMLScriptElement interface ... */
interface HTMLScriptElement extends HTMLElement {

[RyanCavanaugh]

This seems like a TS Server or VS Code problem -- users are likely to be writing this too?

[mjbvz]

Some jsdoc implementations allow using html elements, such as /** text <b>bold</b> */. We strip these in VS Code

In these specific cases, I believe we should escape these elements. I'd expect users to do the same if they were writing the jsdoc comment

[nmain]

Seems like for <b>, the tag is stripped yet the contents remain, but for <script>, the contents are also stripped:

/** no tag <script>script tag</script> <b>b tag</b> */
var a;

https://www.typescriptlang.org/play?#code/PQKhAIDsHtwFwIYHNwB4DOBjATgSwA5wB8Weh8yqwpBxaARkfRUlY+CMAFABuC24BAG4uQA

[RyanCavanaugh]

I'm confused how this works. If I write

/** Comment <neat> here */
const a = 0;

Then the display is Comment here. Why does <script> eat the trailing content but not neat ?

VS Code eating the HTML tags feels like a bug. My intuition is that text inside comments should be treated like <pre></pre> unless we have indications otherwise. I'm open to evidence that people are writing backticked markdown in comments today, but I can't find any evidence of that.

[mjbvz]

Even if we didn't strip the html, it still makes more sense to use markdown code for to display this rather than plain text

The reason <script> deletes the rest of the content is because we completely remove non-text html elements. For text elements such as <b>, we remove the tag but try to preserve the text content