No way to annotate the parameters on function types

By "function type" I'm referring to the fun(param:type):return syntax, when used in a @type, @param, or @overload annotation. What I would like to do is to give a description for each parameter in the function type, but there doesn't seem to be any syntax that supports this. The @param annotation only applies to a literal code function, and I can't split the function type across multiple lines like I can with an enum definition.

Here are some examples of what I mean.

1. Since the LuaDoc does not understand metafunctions, I've used ---@type fun... in a number of places to annotate objects that have a __call metafunction.

---@type fun(x:integer, y:integer)
---@param x integer The x coordinate of the map  <-- This does nothing
---@param y integer The y coordinate of the map  <-- This does nothing
map = setmetatable({}, {
    __call = function(self, x, y)
        return self[x + y * self.width]
    end
})

map.width = 0
map.height = 0

When hovering over map, I would like to see a tooltip similar to the following:

global map: fun(x: integer, y: integer) {
    height: integer = 0,
    width: integer = 0,
}
@param x — The x coordinate of the map
@param y — The y coordinate of the map

---

2. Sometimes, I want to declare that a class has a function on it, without explicitly defining that function. This could be a class method, but more often it's a callback – the intent is for someone to assign a function with the required signature to that key.

---@class text_field
---@param value string The new value of the field  <-- This does nothing
---@field onmodify fun(value:string)

---@return text_field
function make_text_field() end

-- Client code:
local f = make_text_field()
function f.onmodify(val) end

local new_val
f.onmodify(new_val)

When hovering over f.onmodify, I would like to see a tooltip similar to the following:

function f.onmodify(val:string)
@param val — The new value of the field

---

3. Sometimes a function needs to take a callback function as a parameter. In this case, I want to describe the parameters to that passed in function.

---@param list string
---@param value string The current value  <-- This does nothing
---@param fcn fun(value:string)
function foreach(list, fcn) end

-- Client code:
foreach({'a','b','c'}, function(s) end)

When hovering over callback, I would like to see a tooltip similar to the following:

function (s:string)
@param s — The current value

---

4. Sometimes a function needs to return a function, and I would like to describe the parameters the new function takes.

---@param expression string
---@param params table Params to pass to the formula  <-- This does nothing
---@return fun(params:table):number
function parse(expression) end

-- Client code:
local formula = parse "a + 2"
formula{a = 5}

When hovering over formula, I would like to see a tooltip similar to the following:

function formula(params:table):number
@param params — Params to pass to the formula

---

5. When specifying alternate parameter lists with @overload, I'd like to be able to give a description of the other parameters.

---@alias location {x:integer, y:integer}
---@param x integer X coordinate
---@param y integer Y coordinate
---@param loc location X and Y coordinate  <-- This is a warning
---@overload fun(loc:location)
function draw(x, y) end

When hovering over draw, I would like to see a tooltip similar to the following:

(2 definitions, 2 prototypes)
(1) function draw(loc: location)
(1) function draw(x: integer, y: integer)
@param x — X coordinate
@param y — Y coordinate
@param loc — X and Y coordinate

In this last case, the tooltip actually looks almost like the above, although the final line is formatted like a header for some reason. However, there's also an "undefined param loc" warning."

Bắt đầu bằng việc xem xét cách xử lý LuaDoc hiện có đối với các kiểu hàm, các chú thích @param và @overload, sau đó so sánh đầu ra hover trong năm ví dụ. Công việc được xem là hoàn tất khi một cú pháp chú thích được hỗ trợ có thể mô tả các tham số bên trong kiểu hàm và những mô tả đó xuất hiện trong các hover liên quan mà không tạo ra các cảnh báo sai về tham số chưa được định nghĩa.