Skip to content

@enum and @alias comments rendered as markdown #3258

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tommaisey wants to merge 5 commits into
base: master
Choose a base branch
from
+109 −104
Open

@enum and @alias comments rendered as markdown #3258

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
20ad88e
Render enum/alias comments as markdown
tommaisey Aug 21, 2025
5b8acd4
Update changelog for alias markdown rendering
tommaisey Aug 21, 2025
8d12152
Fix alias markdown rendering (use header)
tommaisey Aug 22, 2025
d5279fa
Alias markdown hover does not repeat description
tommaisey Mar 25, 2026
01c48a0
Clean up some code in hover/init.lua loop
tommaisey Mar 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
## Unreleased
<!-- Add all new changes here. They will be moved under a version at release -->
* `CHG` Modified the `ResolveRequire` function to pass the source URI as a third argument.
* `NEW` Render `@alias` value types with markdown instead of code blocks

## 3.17.1
`2026-01-20`
Expand Down
59 changes: 35 additions & 24 deletions script/core/hover/description.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -212,11 +212,11 @@ local function lookUpDocComments(source)
return table.concat(lines, '\n')
end

local function tryDocClassComment(source)
local function tryDocClassComment(source, types)
types = types or {['doc.class'] = true}

for _, def in ipairs(vm.getDefs(source)) do
if def.type == 'doc.class'
or def.type == 'doc.alias'
or def.type == 'doc.enum' then
if types[def.type] then
local comment = getBindComment(def)
if comment then
return comment
Expand All @@ -238,7 +238,9 @@ local function buildEnumChunk(docType, name, uri)
end
local enums = {}
local types = {}
local lines = {}
local lines = {('#### %s:'):format(name)}
local commentTypes = {['doc.enum'] = true, ['doc.alias'] = true}

for _, tp in ipairs(vm.getDefs(docType)) do
types[#types+1] = vm.getInfer(tp):view(guide.getUri(docType))
if tp.type == 'doc.type.string'
Expand All @@ -247,33 +249,39 @@ local function buildEnumChunk(docType, name, uri)
or tp.type == 'doc.type.code' then
enums[#enums+1] = tp
end
local comment = tryDocClassComment(tp)

local comment = tryDocClassComment(tp, commentTypes)
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)
if #lines > 1 then
lines[#lines+1] = ""
end

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
local len = #enumDes
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
Expand Down Expand Up @@ -391,7 +399,7 @@ local function getFunctionCommentMarkdown(source, raw)
end

local enums = getBindEnums(source, docGroup)
md:add('lua', enums)
md:add('md', enums)

return md
end
Expand All @@ -406,21 +414,24 @@ local function tryDocComment(source, raw)
md:add('md', getFunctionCommentMarkdown(source, raw))
source = source.parent
end

local comment = lookUpDocComments(source)
md:add('md', comment)

if source.type == 'doc.alias' then
local enums = buildEnumChunk(source, source.alias[1], guide.getUri(source))
md:add('lua', enums)
end
if source.type == 'doc.enum' then
or tryDocClassComment(source, {['doc.alias'] = true})

md:add('md', enums)
elseif source.type == 'doc.enum' then
local enums = buildEnumChunk(source, source.enum[1], guide.getUri(source))
md:add('lua', enums)
or tryDocClassComment(source, {['doc.enum'] = true})

md:add('md', enums)
end

local result = md:string()
if result == '' then
return nil
end
return result
return result ~= '' and result or nil
end

---@async
Expand Down
35 changes: 11 additions & 24 deletions script/core/hover/init.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,20 +56,13 @@ local function getHover(source, level)
local oop
if vm.getInfer(source):view(guide.getUri(source)) == 'function' then
local defs = vm.getDefs(source)

-- make sure `function` is before `doc.type.function`
local orders = {}
for i, def in ipairs(defs) do
if def.type == 'function' then
orders[def] = i - 20000
elseif def.type == 'doc.type.function' then
orders[def] = i - 10000
else
orders[def] = i
end
end
local orders = {'function', 'doc.type.function'}
table.sort(defs, function (a, b)
return orders[a] < orders[b]
return (orders[a.type] or (#orders + 1)) < (orders[b.type] or (#orders + 1))
Copy link
Contributor

@C3pa C3pa Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This repeatedly calls #orders for defs with a type that's not in the orders array. Obviously, I don't have any benchmarking data here, but you could cache the orders size outside the callback function.

end)

local hasFunc
for _, def in ipairs(defs) do
if guide.isOOP(def) then
Expand All @@ -90,21 +83,15 @@ local function getHover(source, level)
end
else
addHover(source, true, oop)

for _, def in ipairs(vm.getDefs(source)) do
if def.type == 'global'
or def.type == 'setlocal' then
goto CONTINUE
end
if guide.isOOP(def) then
oop = true
end
local isFunction
if def.type == 'function'
or def.type == 'doc.type.function' then
isFunction = true
if def.type ~= 'global'
and def.type ~= 'setlocal' then
oop = oop or guide.isOOP(def)
local isFunction = def.type == 'function' or def.type == 'doc.type.function'

addHover(def, isFunction, oop)
end
addHover(def, isFunction, oop)
::CONTINUE::
end
end

Expand Down
118 changes: 62 additions & 56 deletions test/crossfile/hover.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -274,7 +274,7 @@ TEST {

function mt:add(a, b)
end

return function ()
return setmetatable({}, mt)
end
Expand Down Expand Up @@ -431,11 +431,9 @@ function f(x: string|"选项1"|"选项2")

---

```lua
x:
| "选项1" -- 注释1
-> "选项2" -- 注释2
```]]
#### x:
- `"选项1"` — 注释1
- `"选项2"` (default) — 注释2]]
}

TEST {
Expand All @@ -460,11 +458,9 @@ function f(x: "选项1"|"选项2")

---

```lua
x:
| "选项1" -- 注释1
-> "选项2" -- 注释2
```]]
#### x:
- `"选项1"` — 注释1
- `"选项2"` (default) — 注释2]]
}

TEST {
Expand All @@ -490,11 +486,9 @@ function f()

---

```lua
x:
| "选项1" -- 注释1
-> "选项2" -- 注释2
```]]
#### x:
- `"选项1"` — 注释1
- `"选项2"` (default) — 注释2]]
}

TEST {
Expand All @@ -520,11 +514,9 @@ function f()

---

```lua
return #1:
| "选项1" -- 注释1
-> "选项2" -- 注释2
```]]
#### return #1:
- `"选项1"` — 注释1
- `"选项2"` (default) — 注释2]]
}

TEST {
Expand Down Expand Up @@ -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',
Expand Down Expand Up @@ -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',
Expand Down Expand Up @@ -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 {
Expand Down Expand Up @@ -1526,6 +1512,7 @@ TEST {
{
path = 'a.lua',
content = [[
---Description comment
---@alias A
---| 1 # comment1
---| 2 # comment2
Expand All @@ -1541,11 +1528,32 @@ local x: 1|2

---

#### A:
Description comment

- `1` — comment1
- `2` — comment2]]
}

TEST {
{
path = 'a.lua',
content = [[
---Description comment
---@alias A number

---@type A
local <?x?>
]]
},
hover = [[
```lua
A:
| 1 -- comment1
| 2 -- comment2
```]]
local x: number
```

---

Description comment]]
}

TEST {
Expand Down Expand Up @@ -1663,7 +1671,7 @@ TEST {
content = [[
---@alias someType
---| "#" # description

---@type someType
local <?someValue?>
]]
Expand All @@ -1675,10 +1683,8 @@ local someValue: "#"

---

```lua
someType:
| "#" -- description
```]]
#### someType:
- `"#"` — description]]
}

TEST { { path = 'a.lua', content = [[
Expand Down
Loading