@enum and @alias comments rendered as markdown

changelog.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 <!-- Add all new changes here. They will be moved under a version at release -->
+* `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.

script/core/hover/description.lua

@@ -250,30 +250,34 @@ 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)
+    if #lines > 0 and lines[#lines] ~= "" then
+        lines[#lines+1] = ""
+    end
+    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 +395,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 +414,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

@@ -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 <?someValue?>
         ]]
@@ -1675,10 +1659,8 @@ local someValue: "#"
 
 ---
 
-```lua
-someType:
-    | "#" -- description
-```]]
+#### someType:
+  - `"#"` — description]]
 }
 
 TEST { { path = 'a.lua', content = [[