Render enum/alias comments as markdown

Author: tommaisey

script/core/hover/description.lua

@@ -250,30 +250,31 @@ 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
             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
@@ -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

test/crossfile/hover.lua

@@ -243,7 +243,7 @@ TEST {
 
             function mt:add(a, b)
             end
-            
+
             return function ()
                 return setmetatable({}, mt)
             end
@@ -400,11 +400,9 @@ function f(x: string|"选项1"|"选项2")
 
 ---
 
-```lua
-x:
-    | "选项1" -- 注释1
-   -> "选项2" -- 注释2
-```]]
+**x**:
+  - `"选项1"` — 注释1
+  - `"选项2"` (default) — 注释2]]
 }
 
 TEST {
@@ -429,11 +427,9 @@ function f(x: "选项1"|"选项2")
 
 ---
 
-```lua
-x:
-    | "选项1" -- 注释1
-   -> "选项2" -- 注释2
-```]]
+**x**:
+  - `"选项1"` — 注释1
+  - `"选项2"` (default) — 注释2]]
 }
 
 TEST {
@@ -459,11 +455,9 @@ function f()
 
 ---
 
-```lua
-x:
-    | "选项1" -- 注释1
-   -> "选项2" -- 注释2
-```]]
+**x**:
+  - `"选项1"` — 注释1
+  - `"选项2"` (default) — 注释2]]
 }
 
 TEST {
@@ -489,11 +483,9 @@ function f()
 
 ---
 
-```lua
-return #1:
-    | "选项1" -- 注释1
-   -> "选项2" -- 注释2
-```]]
+**return #1**:
+  - `"选项1"` — 注释1
+  - `"选项2"` (default) — 注释2]]
 }
 
 TEST {
@@ -717,11 +709,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',
@@ -1020,13 +1010,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',
@@ -1243,23 +1231,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 {
@@ -1510,11 +1496,9 @@ local x: 1|2
 
 ---
 
-```lua
-A:
-    | 1 -- comment1
-    | 2 -- comment2
-```]]
+**A**:
+  - `1` — comment1
+  - `2` — comment2]]
 }
 
 TEST {
@@ -1632,7 +1616,7 @@ TEST {
         content = [[
             ---@alias someType
             ---| "#" # description
-            
+
             ---@type someType
             local <?someValue?>
         ]]
@@ -1644,10 +1628,8 @@ local someValue: "#"
 
 ---
 
-```lua
-someType:
-    | "#" -- description
-```]]
+**someType**:
+  - `"#"` — description]]
 }
 
 TEST { { path = 'a.lua', content = [[