@see does not display on a new line

[carsakiller]

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?

Annotations, Hover, Libraries

Expected Behaviour

It would be much easier to read if @see appeared on a new line:

Also, it only says "See:" instead of "@see". I think it makes sense for it to say so to match @param, @return, etc.

Actual Behaviour

The @see annotation appears on the same line as the previous annotation:

Reproduction steps

1. Use the following code:

server = {}

---Does something
function onCustomCommand() end

---Sends a message to all running scripts.
---@param message string message
---@see onCustomCommand
function server.command(message) end

2. Hover over server.command
3. Note "See:" displayed on the same line as @param

Additional Notes

No response

Log File

No response

[carsakiller]

It may actually be best to just rethink how we can link to symbols in the workspace.

Typescript handles this using an “inline tag”, but I think we can do one better.

We can instead use normal Markdown links, allowing users to use them any way they like – no worrying about how the language server formats it. It also allows us to fit the link in to our paragraph anywhere we like, rather than just at the bottom. We could look for a character like @ or $ in a markdown URL and replace it with the URI for the actual referenced symbol.

Something like this:

---Is linked to
---@class Object

---Is linked to
local function getID() end

---This function does something really cool. To get the ID, see [getID]($getID).
---
---Example of referencing some core Lua stuff, like [table.insert]($table.insert).
---@param id integer The ID to use for this function
---@return Object obj The [`Object`]($Object) retrieved
---You can even still do the current style:
---See:
---- [Object]($Object)
local function getObject(id) end

If this is something that is possible, I think this is a much better long-term solution. I can close this issue and open a new one for this feature if needed.

[carsakiller]

Closing this in favour of #2175