Improvements to `@see` and `@source`

[carsakiller]

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.

[carsakiller]

Just saw the new @source tag, that should probably also allow linking to files in the workspace as explained above. It isn't too helpful if you absolutely link to a source and when someone else opens the file the path doesn't match and an error is thrown.

[carsakiller]

Another feature for this that I could see being very useful is linking to an actual function within a file.

---@see http.get
function get(url) end

This would require the text after @see to be parsed and then we would have to find the definition of the symbol (like how the "Go To Definition" command works).

Clicking on the link in the hover window would then go to the definition of the selected class/function/etc.

This is probably the better way to implement it seeing as there is also @source now. My thinking goes like this:

I want to link to the function I am wrapping

Use @see:

---@see class.function
function myWrapper() end

I want to link to a website where I got this code from

Use @source:

---@source https://example.com
function fromTheInternet() end

So @see is used for linking within this project or to a library defined in the extension's settings and @source is for linking a URL to a website.

[sumneko]

source is an internally used annotation, you can pretend it doesn't exist. Perhaps a better name would be shadow .

[carsakiller]

Now I am really confused as to what @source does 😄. Do you have an example in the server you could link to?

I think a better name would just be @link or @url then for an annotation that lets you link to a website.

[sumneko]

It is used for jumping to another language, for example:

---@source lmathlib.c:220:11
function math.max(...) end

math.max(1, 2)

When requesting goto definition for math.max, it will jump into lmathlib.c instead of lua file.

This is a private feature for $/api/report of https://marketplace.visualstudio.com/items?itemName=CppCXY.emmylua-unity