The Problem

In its current state, @see is relatively useless. It does not actually show up on hover and is currently only really useful if you actually go to the definition of whatever is being defined. Even though http is highlighted in the below image, hovering it does nothing and it has no function. This is okay for referring to a function within the same file but is severely lacking when it comes to libraries.

--- helpers.lua ---
---GET some URL
---@param url string
---@see http
local function get(url)
    local headers = {Authorization = "ABCDEFG"}
    http.get(url, headers)
end
get("localhost")

Besides it not really being visible, it is lacking in usability as it is only good for plain text as far as I can tell. I think it would be super useful if it could be used to link to other files in the workspace (relative to the definition file).

Proposal

EDIT: View my comment below for a more complete solution.

--- helpers.lua ---
---GET some URL
---@param url string
---@see [http Class](workspace/path/to/http)
local function get(url)
    local headers = {Authorization = "ABCDEFG"}
    http.get(url, headers)
end
get("localhost")

Note that the file extension is not included in the path, I think it would be helpful if the .lua file extension were assumed as a default so workspace/path/to/http.lua could be linked to through workspace/path/to/http. Should there be multiple @see tags, I think it should display one per line:

As a bonus, it would be useful if while typing out the path to another file in the workspace, autocompletions were provided as seen below while using the TypeScript extension. This is a nice quality of life feature as it would make it easier to get the path right but is not necessary.