Way to disable HTML tags in hover block

[TIMONz1535]

How are you using the lua-language-server?

Visual Studio Code Extension (sumneko.lua)

Which OS are you using?

Windows

What is the issue affecting?

Hover

Expected Behaviour

Hi. I've come across the fact that some people want to use angle brackets as a classic description for arguments, like command-line arguments <arg>[, arg]. But VS Code automatically considers these HTML tags in hover block and deletes them. I would like to be able to disable this behavior in per-project (workspace or .luarc) and user settings.

-- Adds <amount> of <item> to character.
---@param item string
---@param amount integer
function Character:AddItem(item, amount) end

Also I like to use markdown style, but not html tags.

I found #996 where it feels like html tags can be disabled without disabling markdown - supportHtml.

Actual Behaviour

It ate my names, they're not html tags.

Reproduction steps

1. Place anything in angle brackets in your comment
2. Look, it's gone when you hover

Additional Notes

I found some info on this page https://luals.github.io/wiki/annotations/

The below methods can be added to the end of a line:

    HTML <br> tag (recommended)
    \n newline escape character
    Two trailing spaces (may be removed by formatting tools)
    Markdown backslash \ ( [not recommended](https://www.markdownguide.org/basic-syntax#line-break-best-practices) )

but only the first one seems to work, and the others don't do anything.

Log File

No response

[tomlau10]

I found #996 where it feels like html tags can be disabled without disabling markdown - supportHtml.

Judging from the docs, it means html tag will just be stripped out instead of rendering as plain text when supportHtml = false 🤔

• When supportHtml is false, the markdown renderer will strip out any raw html tags that appear in the markdown text.

I just tested it by changing the value to false in the client side extension here: https://github.com/LuaLS/vscode-lua/blob/f8ecc4bf454f8898fc7818045e1565dc00fbf6ea/client/src/languageserver.ts#L139-L147
(I modify the source code of my locally installed vscode lua extension to test it)

• After changing it to false, the <br> tag no longer works, instead of showing it as plain text <br>

--- line 1<br>
--- line 2
---@class Test
--> hover shows `line 1 line 2`, instead of `line 1\nline2`
--> i.e. `<br>` is just stripped out

• So I don't think there is a way to treat html tag-like text as plain text in a markdown string, unless you escape those "tags" manually.
  For example using backtick code markdown syntax:

-- Adds `<amount>` of `<item>` to character.
---@param item string
---@param amount integer
function Character:AddItem(item, amount) end
--> now the hover can show the whole comment

---

but only the first one seems to work, and the others don't do anything.

I don't know how you tested it, except the \n one, others are working as expected in my side 😕

--- line 1<br>
--- line 2
---@class Test1
--> works

--- line 1\n
--- line 2
---@class Test2
--> not work !!

--- line 1  
--- line 2
---@class Test3
--> works

--- line 1\
--- line 2
---@class Test4
--> works

[TIMONz1535]

Wow, nice research

So I don't think there is a way to treat html tag-like text as plain text in a markdown string

Aww it is sad. I was hoping that the VS Code api wasn't so rough. It looks like the developers have to escape the lines themselves. I mean, maybe it's easier to do this on the LuaLS plugin side when displaying the hovers, like with some known "escapeHTML" methods.

others are working as expected in my side

Oh this should be done in several lines.... :o I was thinking in one because I'm confused by site description:

There are many ways to add newlines to your annotations. The most bulletproof way is to simply add an extra line of just ---, although this functions like a paragraph break, not a newline.

I completely forgot that new --- lines with the text don't make actual new lines. Thanks!

[tomlau10]

maybe it's easier to do this on the LuaLS plugin side when displaying the hovers, like with some known "escapeHTML" methods.

Yeah, that might be a solution. 👍
Say there is a doc.escapeHTML config, and when set to true, then all hover markdown strings will be escaped first:
i.e. < => <, etc.

In addition since <br> is one of the best practices to add line break, maybe this tag should be considered as special case and should never be escaped. 🤔