From 727b9dde98cbf318030b6bf7191d22f266f71058 Mon Sep 17 00:00:00 2001 From: Tom Maisey Date: Thu, 21 Aug 2025 17:40:06 +0100 Subject: [PATCH 1/3] Render enum/alias comments as markdown --- script/core/hover/description.lua | 25 ++++---- test/crossfile/hover.lua | 96 +++++++++++++------------------ 2 files changed, 52 insertions(+), 69 deletions(-) diff --git a/script/core/hover/description.lua b/script/core/hover/description.lua index 368b311c9..3b447d472 100644 --- a/script/core/hover/description.lua +++ b/script/core/hover/description.lua @@ -250,20 +250,21 @@ local function buildEnumChunk(docType, name, uri) local comment = tryDocClassComment(tp) if comment then for line in util.eachLine(comment) do - lines[#lines+1] = ('-- %s'):format(line) + lines[#lines+1] = line end end end if #enums == 0 then return nil end - lines[#lines+1] = ('%s:'):format(name) + lines[#lines+1] = ('**%s**:'):format(name) for _, enum in ipairs(enums) do - local enumDes = (' %s %s'):format( - (enum.default and '->') - or (enum.additional and '+>') - or ' |', - vm.getInfer(enum):view(uri) + local suffix = (enum.default and ' (default)') + or (enum.additional and ' (additional)') + or '' + local enumDes = (' - `%s`%s'):format( + vm.getInfer(enum):view(uri), + suffix ) if enum.comment then local first = true @@ -271,9 +272,9 @@ local function buildEnumChunk(docType, name, uri) for comm in enum.comment:gmatch '[^\r\n]+' do if first then first = false - enumDes = ('%s -- %s'):format(enumDes, comm) + enumDes = ('%s — %s'):format(enumDes, comm) else - enumDes = ('%s\n%s -- %s'):format(enumDes, (' '):rep(len), comm) + enumDes = ('%s\n%s %s'):format(enumDes, (' '):rep(len + 3), comm) end end end @@ -391,7 +392,7 @@ local function getFunctionCommentMarkdown(source, raw) end local enums = getBindEnums(source, docGroup) - md:add('lua', enums) + md:add('md', enums) return md end @@ -410,11 +411,11 @@ local function tryDocComment(source, raw) md:add('md', comment) if source.type == 'doc.alias' then local enums = buildEnumChunk(source, source.alias[1], guide.getUri(source)) - md:add('lua', enums) + md:add('md', enums) end if source.type == 'doc.enum' then local enums = buildEnumChunk(source, source.enum[1], guide.getUri(source)) - md:add('lua', enums) + md:add('md', enums) end local result = md:string() if result == '' then diff --git a/test/crossfile/hover.lua b/test/crossfile/hover.lua index b9377b365..16e4b030e 100644 --- a/test/crossfile/hover.lua +++ b/test/crossfile/hover.lua @@ -274,7 +274,7 @@ TEST { function mt:add(a, b) end - + return function () return setmetatable({}, mt) end @@ -431,11 +431,9 @@ function f(x: string|"选项1"|"选项2") --- -```lua -x: - | "选项1" -- 注释1 - -> "选项2" -- 注释2 -```]] +**x**: + - `"选项1"` — 注释1 + - `"选项2"` (default) — 注释2]] } TEST { @@ -460,11 +458,9 @@ function f(x: "选项1"|"选项2") --- -```lua -x: - | "选项1" -- 注释1 - -> "选项2" -- 注释2 -```]] +**x**: + - `"选项1"` — 注释1 + - `"选项2"` (default) — 注释2]] } TEST { @@ -490,11 +486,9 @@ function f() --- -```lua -x: - | "选项1" -- 注释1 - -> "选项2" -- 注释2 -```]] +**x**: + - `"选项1"` — 注释1 + - `"选项2"` (default) — 注释2]] } TEST { @@ -520,11 +514,9 @@ function f() --- -```lua -return #1: - | "选项1" -- 注释1 - -> "选项2" -- 注释2 -```]] +**return #1**: + - `"选项1"` — 注释1 + - `"选项2"` (default) — 注释2]] } TEST { @@ -748,11 +740,9 @@ function f(a: boolean) @*param* `a` — xxx -```lua -a: - | true -- ttt - | false -- fff -```]]} +**a**: + - `true` — ttt + - `false` — fff]]} TEST {{ path = 'a.lua', content = '', }, { path = 'b.lua', @@ -1051,13 +1041,11 @@ function f(p: 'a'|'b') --- -```lua -p: - | 'a' -- comment 1 - -- comment 2 - | 'b' -- comment 3 - -- comment 4 -```]]} +**p**: + - `'a'` — comment 1 + comment 2 + - `'b'` — comment 3 + comment 4]]} --TEST {{ path = 'a.lua', content = '', }, { -- path = 'b.lua', @@ -1274,23 +1262,21 @@ function f(p: 'a1'|'a2', ...'a3'|'a4') --- -```lua -p: - | 'a1' - | 'a2' +**p**: + - `'a1'` + - `'a2'` -...(param): - | 'a3' - | 'a4' +**...(param)**: + - `'a3'` + - `'a4'` -ret1: - | 'r1' - | 'r2' +**ret1**: + - `'r1'` + - `'r2'` -...(return): - | 'r3' - | 'r4' -```]] +**...(return)**: + - `'r3'` + - `'r4'`]] } TEST { @@ -1541,11 +1527,9 @@ local x: 1|2 --- -```lua -A: - | 1 -- comment1 - | 2 -- comment2 -```]] +**A**: + - `1` — comment1 + - `2` — comment2]] } TEST { @@ -1663,7 +1647,7 @@ TEST { content = [[ ---@alias someType ---| "#" # description - + ---@type someType local ]] @@ -1675,10 +1659,8 @@ local someValue: "#" --- -```lua -someType: - | "#" -- description -```]] +**someType**: + - `"#"` — description]] } TEST { { path = 'a.lua', content = [[ From bd5755716074b145e7808f412a504403fb546f2f Mon Sep 17 00:00:00 2001 From: Tom Maisey Date: Thu, 21 Aug 2025 23:21:58 +0100 Subject: [PATCH 2/3] Update changelog for alias markdown rendering --- changelog.md | 1 + 1 file changed, 1 insertion(+) diff --git a/changelog.md b/changelog.md index 59d4dee24..60fc02225 100644 --- a/changelog.md +++ b/changelog.md @@ -2,6 +2,7 @@ ## Unreleased +* `NEW` Render `@alias` value types with markdown instead of code blocks * `FIX` Incorrect inject-field message for extra table field in exact class * `CHG` Rename configuration option `Lua.diagnostics.disableScheme` to `Lua.diagnostics.validScheme` and improve its description. Now it enables diagnostics for Lua files that use the specified scheme. * `FIX` adds the `|lambda|` operator to the `Lua.runtime.nonstandardSymbol` configuration template, which allows the use of that option. Previously, support for it existed in the parser, but we could not actually use the option because it is not recognised in the configuration. From 2f0116e3354def5602d3928bda9b44d9ec8af1ed Mon Sep 17 00:00:00 2001 From: Tom Maisey Date: Fri, 22 Aug 2025 10:31:02 +0100 Subject: [PATCH 3/3] Fix alias markdown rendering (use header) --- script/core/hover/description.lua | 5 ++++- test/crossfile/hover.lua | 24 ++++++++++++------------ 2 files changed, 16 insertions(+), 13 deletions(-) diff --git a/script/core/hover/description.lua b/script/core/hover/description.lua index 3b447d472..6ddf7495c 100644 --- a/script/core/hover/description.lua +++ b/script/core/hover/description.lua @@ -257,7 +257,10 @@ local function buildEnumChunk(docType, name, uri) if #enums == 0 then return nil end - lines[#lines+1] = ('**%s**:'):format(name) + if #lines > 0 and lines[#lines] ~= "" then + lines[#lines+1] = "" + end + lines[#lines+1] = ('#### %s:'):format(name) for _, enum in ipairs(enums) do local suffix = (enum.default and ' (default)') or (enum.additional and ' (additional)') diff --git a/test/crossfile/hover.lua b/test/crossfile/hover.lua index 16e4b030e..2da636abd 100644 --- a/test/crossfile/hover.lua +++ b/test/crossfile/hover.lua @@ -431,7 +431,7 @@ function f(x: string|"选项1"|"选项2") --- -**x**: +#### x: - `"选项1"` — 注释1 - `"选项2"` (default) — 注释2]] } @@ -458,7 +458,7 @@ function f(x: "选项1"|"选项2") --- -**x**: +#### x: - `"选项1"` — 注释1 - `"选项2"` (default) — 注释2]] } @@ -486,7 +486,7 @@ function f() --- -**x**: +#### x: - `"选项1"` — 注释1 - `"选项2"` (default) — 注释2]] } @@ -514,7 +514,7 @@ function f() --- -**return #1**: +#### return #1: - `"选项1"` — 注释1 - `"选项2"` (default) — 注释2]] } @@ -740,7 +740,7 @@ function f(a: boolean) @*param* `a` — xxx -**a**: +#### a: - `true` — ttt - `false` — fff]]} @@ -1041,7 +1041,7 @@ function f(p: 'a'|'b') --- -**p**: +#### p: - `'a'` — comment 1 comment 2 - `'b'` — comment 3 @@ -1262,19 +1262,19 @@ function f(p: 'a1'|'a2', ...'a3'|'a4') --- -**p**: +#### p: - `'a1'` - `'a2'` -**...(param)**: +#### ...(param): - `'a3'` - `'a4'` -**ret1**: +#### ret1: - `'r1'` - `'r2'` -**...(return)**: +#### ...(return): - `'r3'` - `'r4'`]] } @@ -1527,7 +1527,7 @@ local x: 1|2 --- -**A**: +#### A: - `1` — comment1 - `2` — comment2]] } @@ -1659,7 +1659,7 @@ local someValue: "#" --- -**someType**: +#### someType: - `"#"` — description]] }