Inline "named arguments" in a function's hover docs

[idanarye]

Lua has a named arguments pattern where you pass all the named arguments inside a table. This can be supported in LuaLS by declaring a class for the arguments table:

---@class FooArgs
---@field bar number The `bar` argument
---@field baz string The `baz` argument
---@field qux boolean The `qux` argument

---The `foo` function
---@param args FooArgs Named arguments
local function foo(args)
    -- ...
end

And it gives you completion, linting, and hover docs for the fields:

But the hover for the function itself only shows the opaque type:

If would be nice if, instead, we could have something like this:

function foo(args: FooArgs)

─────────────────────────────────
The foo function

@param args — Named arguments:

• bar: number — The bar argument
• baz: string — The baz argument
• qux: boolean — The qux argument

This will also look nicer in the generated docs.

Of course, this should not be the default behavior. I'm thinking of two options for this syntax:

1. A modifier to ---@param:

   ---The `foo` function
   ---@param (inline) args FooArgs Named arguments
   local function foo(args)
       -- ...
   end

2. Specifying the "paths" of the table fields:

   ---The `foo` function
   ---@param args FooArgs Named arguments
   ---@param args.bar number The `bar` argument
   ---@param args.baz string The `baz` argument
   ---@param args.qux boolean The `qux` argument
   local function foo(args)
       -- ...
   end

[tomlau10]

I think you can enable inlay hint ("Lua.hint.enable": true)
That way when you are calling the function, you can see the param name, and its hover docs should be what you want.

Another useful extension setting is to show param name only when it's literal ("Lua.hint.paramName": "Literal")
Such that the inline hint will not be too distracting 😃