Improvements to variable arguments and returns

[carsakiller]

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

1. @vararg vs @param
2. @return varargs
3. Ambiguous enums

@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(...) end

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

[sumneko]

Thank you for your suggestion

@vararg is mainly for compatibility with standard EmmyLua, and I don't like it either.

Your suggestion points out a lot of details, which I have not carefully considered. I think your design is good, and I can follow your design.

Let's turn this discussion into an issue so I can keep track of it.