Feature request: New rule to check for properly escaping "<" and ">" characters

[iliubinskii]

Motivation

/**
 * Returns Set<string>.
 *
 * @returns Set<string>.
 */
export function f(): Set<string> {
  return new Set([]);
}

VSCode does not show ""

/**
 * Returns Set\<string\>.
 *
 * @returns Set\<string\>.
 */
export function f(): Set<string> {
  return new Set([]);
}

The escaped version works:

Current behavior

Escaping "<" and ">" is not checked.

Desired behavior

New rule to enforce escaping "<" and ">".

[brettz9]

Is this not a bug of VSC? Why is there any need for escaping with backslashes? This does not seem part of JSDoc that I'm aware of either...

[iliubinskii]

This is not vscode bug.

Here is typescript playground example:
https://www.typescriptlang.org/play#code/PQKhCgAIUgRB7AxgVwLYFMB2AXAhtgS3kyhgCV1F4AnAEwB4AVAPgDpThx0APABxuyQAZskyJCxYQAoAlAC5IAN3gFakAN4BfIA

I guess that <...> in documentation comments is interpreted as HTML tag = it is not shown as plain text.

If you don't find it useful to add new rule in your plugin - no problem. I can write my own rule for this.

[brettz9]

I see. So we're deliberately not talking about within types here--only the descriptions.

Note that, like for XML, one doesn't actually need to escape >, but one does need to escape < (and in the event one wishes to have a numeric character reference show up, one has to escape ampersands too, e.g., \ꯍ instead of &#abcd;.

Note too that one can use any of the XML/HTML5 predefined entities (&, <, >, ", ') like ꯍ.

And interestingly, one can also use yet another escape mechanism, the Markdown-style backticks (e.g., `ꯍ`).

This is somewhat related to #710 (though yours is as a new rule and doesn't relate to that particular escaping problem).

There is kind of a problem as far as the latter not apparently being fully settled on per microsoft/tsdoc#166 .

However, I'm starting to think it is a good idea to at least allow configurable support for such escapes, even though I'd really prefer if a standard were coming that we could wait for. But I think we should go with configuration to support which is effectively the de facto standard now, TypeScript (and its tooling).

One trick for this latter problem is that the backslash in *\/ does not mean that a visible backslash needs to be doubled everywhere (you do need to double it to *\\/ if you want to show *\/). Also if you do double it (anywhere), it will only show once. Likewise, backticks do not need to be double-escaped to show a literal.

As to a course of action, I think this proposed rule should have configuration as to whether < and & should require escaping, and configuration for the fixer to decide which kind to apply (backslashes or predefined entities at least). Auto-adding backticks would require grabbing until the end of the sequence so as to encapsulate the whole, e.g., & to `&` and might be problematic, as with backslashes, if found immediately after another of its kind, e.g., the unescaped `઼ would become the still unescaped ``઼`). But if we note that backticks and backslashes are potentially problematic for auto-fixing in this way we could still offer them since not everyone will want to use the uglier predefined entities. I don't think we need to have code to require escaping of > (nor of course for " or ').

Not everyone will want this rule, however, as sometimes one intentionally wants to use HTML elements. We could in theory also provide an option to auto-escape backslashes or backticks to avoid unintended escaping, but that would probably not be desired by most (and fixers would need one mechanism).

[gajus]

🎉 This issue has been resolved in version 39.5.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀