LuaLS / LuaLS/lua-language-server
Annotations `@enum` and `@enum (key)` in JSON output
Nobody has claimed this yet.
- Dominant language
- Lua
- Stars
- 4.4k
- Forks
- 442
- PR merge metrics
- No merged PRs in 30d
Description
Annotations @enum and @enum (key) produce very different JSON output.
Annotation @enum
---@enum level1
---Description of enum level1.
local level1 = {
low = 1, --Low level.
high = 2, --High level.
}
This enum creates the following JSON output:
{
"defines": [
{
"file": "file:///home/andreas/Projects/Code/luals2dox/test/./enum/enum-02.lua",
"finish": 15,
"start": 9,
"type": "doc.enum"
}
],
"desc": "```lua\n{\n low: integer = 1,\n high: integer = 2,\n}\n```",
"fields": [],
"name": "level1",
"rawdesc": "```lua\n{\n low: integer = 1,\n high: integer = 2,\n}\n```",
"type": "type"
},
{
"defines": [
{
"file": "file:///home/andreas/Projects/Code/luals2dox/test/./enum/enum-02.lua",
"finish": 40007,
"start": 40003,
"type": "tablefield"
}
],
"desc": "High level.",
"fields": [],
"name": "level1.high",
"rawdesc": "High level.",
"type": "type"
},
{
"defines": [
{
"file": "file:///home/andreas/Projects/Code/luals2dox/test/./enum/enum-02.lua",
"finish": 30006,
"start": 30003,
"type": "tablefield"
}
],
"desc": "Low level.",
"fields": [],
"name": "level1.low",
"rawdesc": "Low level.",
"type": "type"
},
Issues:
- First block:
startandfinishnumbers are wrong. - Description of enum
Description of enum level1.is missing.
Just curious:
- Why are there 3 separate blocks for this enum? I'd expected block 2 and 3 (enum items) to be sub-blocks of block 1 (enum). This would make it easier reading/postprocessing the JSON file.
Annotation @enum (key)
---@enum (key) level2
---Description of enum level2.
local level2 = {
low = 1, --Low level.
high = 2, --High level.
}
This enum create the following JSON output:
{
"defines": [
{
"file": "file:///home/andreas/Projects/Code/luals2dox/test/./enum/enum-02.lua",
"finish": 70021,
"start": 70015,
"type": "doc.enum"
}
],
"desc": "```lua\n\"low\" | \"high\"\n```",
"fields": [],
"name": "level2",
"rawdesc": "```lua\n\"low\" | \"high\"\n```",
"type": "type"
},
Issues:
- Description of enum
Description of enum level2.is missing. - Description of enum items
Low level.andHigh level.are missing.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Reproduce the two annotated enum examples from the issue and inspect the language server's annotation-processing and JSON-output entry points. Compare source ranges and propagated descriptions for the enum and its items. Done means both forms preserve the enum and item descriptions and report correct start/finish values, with the output structure matching the project's intended behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- lua
- Domain
- devtools
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100