LuaLS / LuaLS/lua-language-server

Annotations `@enum` and `@enum (key)` in JSON output

Open
#2,530 1 comment 0 reactions 0 assignees View on GitHub

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: start and finish numbers 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. and High level. are missing.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.