Skip to content

Improvements to @see and @source #1344

Closed
@carsakiller

Description

@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")

image

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")

image

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:
image

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.
image

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestfeat/LuaCats AnnotationsRelated to Lua Language Server Annotations (LuaCats)

    Type

    No type

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions