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

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.

issue にある注釈付き enum の 2 つの例を再現し、アノテーション処理と JSON 出力における language server のエントリーポイントを調べます。enum とその項目について、ソース範囲と伝播された説明を比較します。両方の形式で enum と項目の説明が保持され、正しい開始値と終了値が報告され、出力構造がプロジェクトの意図した動作と一致すれば完了です。