How to document a function that receives a dictionary?

[rodrigoduartetapps]

Hello everyone,

I'm interested in starting to use LuaLS in my projects, but I have a more beginner-oriented question. I have several methods in my projects that receive a parameter dictionary, as exemplified below:

--- Loads an atlas.
--- @param params {imageName: string, info: string, size: number}
--- @return Atlas
function Atlas.loadAtlas(params)
    -- Implementation here
end

Documenting it this way, I encountered two issues:

1. The first and more significant problem is that I can't add comments to describe each field in the dictionary (imageName, info, etc.).

2. The second problem occurs when using the function and passing an undocumented parameter, for example:

Atlas.loadAtlas({teste = true})

In this case, no error is generated. Is there any way to solve these problems?

Thanks in advance for your help!

[goldenstein64]

You can document your parameter dictionary using a @class annotation and subsequent @field annotations, i.e.

---you can put general documentation about your dictionary type here
---@class AtlasParams
---
---you can put field documentation here
---@field imageName string # or field docs here
---
---more documentation
---@field info string
---
---more docs
---@field size number

---@param params AtlasParams
function Atlas.loadAtlas(params)
  -- implementation
end

Atlas.loadAtlas({ test = true }) -- Missing required fields in type `AtlasParams`: `imageName`, `info`, `size`

[rodrigoduartetapps]

Hello @goldenstein64, thank you for your assistance.

I believe that replicating this solution in my case might be a bit challenging. I have several (M) modules with various methods (N), so creating a parameter class for each of the N methods would result in M classes, making it M * N the total number of classes, which could become quite extensive.

However, the main issue is not the scalability. The key concern lies in another aspect:

The autocomplete suggestion shows that the function expects AtlasParams, but it doesn't reveal the fields within AtlasParams, let alone the documentation for those fields. I find this information crucial for my workflow. If there were a way to display the documentation for the fields in a parameter table in the same manner as individual parameters, that would be incredible. However, I assume this feature is not currently implemented, correct?

Once again, I appreciate your help!

[goldenstein64]

That seems to be the case at first, but it should be possible in VS Code at least.

I had to trigger suggestions manually though, by pressing ctrl+space.

As for your issues with the large number of classes to document, it may be possible to lessen the work using inheritance, although it won't make the inherited fields required for some reason.

---@class ImageParams
---@field imageName string
---@field size number

---@class InfoParams
---@field info string

-- contains all fields from ImageParams and InfoParams
---@class AtlasParams : ImageParams, InfoParams
-- no need to write additional fields

Atlas.loadAtlas({}) -- no warnings

[rodrigoduartetapps]

WOW, I think your response addressed my doubts and met the needs I had. I wasn't aware of the Ctrl+Space within the table with field suggestions and their documentation. Thank you so much for your help, @goldenstein64!