No way to annotate the parameters on function types

[CelticMinstrel]

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

[sumneko]

interface required

[bavalpey]

Is there any information on this?

Trying to hack my way through accomplishing this in definition files for an API I'm working on adding LSP support for.