Request for the ability to annotate non-defined functions like classes

[Arxareon]

Hello!

I think it'd be really useful if we could annotate @param and @return descriptions for not yet defined functions named like classes and then apply that list of descriptions to the type of a @field or to any variable through @type. If I use virtual or abstract functions in other languages to be implemented later, I can usually add detailed annotations to them which the implementation would also inherit.

The current extent of predescribing a function used as a type gets exhausted in fun([param: type...]): [return: type...], which already is nice but I really miss the ability to add individual descriptions to and perhaps additional note lines under each parameter and return value.

An example of how it could look like:

---@function function_name fun(p: type): r: type
---@param p type Description
--- - Additional notes..
---@return r type Description
--- - Additional notes..
--- - more points..

utilizing a possible new annotation keyword of @function [name] [fun(...) type]

to be used as:

---@type function_name
local function f() end

or:

---@class class_name
---@field f function_name

If there already is a way to do this or a good way to achieve the same result, please let me know! I'd be very happy if I could annotate like this. Thank you in advance!

[Arxareon]

It'd also be useful in being able to assign detailed annotations for functions that cannot be defined as a named function - example:

local t = {
	[1] = {},
	[2] = {},
	[3] = {},
}

for i = 1, #t do
	---@type specified_function_typeName
	t[i].f = function() print(i) end
end

[carsakiller]

I think this is a duplicate of #1456. The conclusion we came to is that there should be a @function annotation to allow better documenting of non-defined functions.

[Arxareon]

It's not quite a duplicate but there is mention of an abstract/pre-defined @function annotation but that should be used like @type and not as an overload.

I would actually expect warnings when the function definition does not match the pre-described annotations being applied to it - i.e. when it's implemented.

Not sure if this should be closed yet, because that's not exactly what I read in the mentioned issue - but it may still very well be what you mean as well.

If anything, what's described in this comment #2415 (comment) is a duplicate of this. I'm not sure why you closed & tagged it as not planned and I think there may be a misunderstanding which I'd love to clear up given the chance.

Are we in fact talking about the same thing (I described above) and is what I'm suggesting not planned, or you used not planned to get rid of the multiple threads of speak about similar issues (in which case, fair enough but I'm not sure we are on the same page yet?

[carsakiller]

That issue asks for the implementation of a @function annotation that supports defining functions as in-depth as the current @class annotation. It could then be used for overloads, types, and should be diagnosed like you mention.

#2415 was closed by its author when I pointed out the existence of #1456. This functionality has been requested by many people, so I am just trying to keep everything in one place when the solution is to add a @function annotation so that nothing is missed. If you would like, you could comment on that issue your specific use case with @type so we can make sure that is considered.