Improvements to variable arguments and returns #1207
Description
Discussed in #1206
Originally posted by carsakiller June 14, 2022
Introduction
Currently, there are multiple ways to document a variable number of parameters passed to a function but I think they are causing confusion and conflicting with each other.
There is also only one way to document a variable number of return values, which I think is even more problematic.
Problems
@vararg vs @param
You have two options when documenting a variable number of parameters passed to a function:
Use @vararg
This means it can have a type, but no description
Example
---Concat strings together
---@vararg string The strings to concat
function concat(...) end
Use @param
This means it can have a name (...), type, and description
Example
---Concat strings together
---@param ... string The strings to concat
function concat(...) end
The obvious choice is to use @param - which makes @vararg completely useless.
@return varargs
When returning a variable number of values from a function, there are two options:
Follow standard usage
The standard usage of @return is @return <type> [name] [description]. However, this results in the name ... not being parsed correctly.
Example
---@alias color
---| '"red"'
---| '"blue"'
---@alias hex string A hexadecimal value representing a color e.g. #ffffff
---Convert color name to hex value
---@param ... color The names of the colors to convert
---@return hex ... The colors converted to hexadecimal
function colorToHex(...)
return ...
end
This doesn't look great and it only keeps track of the type for the first return value:
Inverted usage
Using @return <name> <type> <description> is a terrible idea... but it does at least parse ... correctly...
Example
---@alias color
---| '"red"'
---| '"blue"'
---@alias hex string A hexadecimal value representing a color e.g. #ffffff
---Convert color name to hex value
---@param ... color The names of the colors to convert
---@return ... hex The colors converted to hexadecimal
function colorToHex(...)
return ...
end
This comes at the cost of completely ruining any kind of type tracking:
Ambiguous enums
Should your function both receive and return a variable number of values and it uses an enum, it becomes a little ambiguous as to what the provided documentation is referring to.
I am aware that these values are also listed at the top next to the parameter, but (and especially with how variable returns are currently displayed) it appears that the enum at the bottom is also referring to the return values.
Proposed Solutions
Solution to @vararg vs @param
I think that @vararg should just be removed in favor of using @param as it is able to do a better job at documenting variable parameters. It is confusing to have a tag for documenting parameters but then another tag to document multiple parameters and I feel it is more intuitive to only use @param, like so:
---@param ... string The strings to concat together
function concat(...) endSolution to @return varargs
The current syntax of @return <type> [name] [description] should be kept and ... should be a valid return name that gets parsed as any other name does. This should result in:
Solution to Ambiguous enums
As for this problem, I am not sure how it can best be solved, please do offer some ideas.
Maybe the enum reference appears immediately after the param/return that references it. This would probably require splitting the annotation that the user is providing in order to insert this info between @ tags. This would definitely make it clear but it could lead to lots of spacing between params/returns should the enum have a lot of options.
This seems like it could cause lots of problems.
Another possible solution could be to automatically label the parameter vararg ... (param) and the return one ... (return) just so they cannot be confused.