improve ---@see

resolve #1344

Author: sumneko

Diff for: changelog.md

@@ -104,6 +104,7 @@ server will generate `doc.json` and `doc.md` in `LOGPATH`.
   }
   ```
 * `CHG` find reference: respect `includeDeclaration` (although I don't know how to turn off this option in VSCode)
+* `CHG` [#1344] improve `---@see`
 * `FIX` [#1567]
 * `FIX` [#1593]
 * `FIX` [#1595]
@@ -118,6 +119,7 @@ server will generate `doc.json` and `doc.md` in `LOGPATH`.
 [#1177]: https://github.com/sumneko/lua-language-server/issues/1177
 [#1202]: https://github.com/sumneko/lua-language-server/issues/1202
 [#1332]: https://github.com/sumneko/lua-language-server/issues/1332
+[#1344]: https://github.com/sumneko/lua-language-server/issues/1344
 [#1458]: https://github.com/sumneko/lua-language-server/issues/1458
 [#1557]: https://github.com/sumneko/lua-language-server/issues/1557
 [#1558]: https://github.com/sumneko/lua-language-server/issues/1558

Diff for: script/core/hover/description.lua

@@ -7,6 +7,7 @@ local util     = require 'utility'
 local guide    = require 'parser.guide'
 local rpath    = require 'workspace.require-path'
 local furi     = require 'file-uri'
+local wssymbol = require 'core.workspace-symbol'
 
 local function collectRequire(mode, literal, uri)
     local result, searchers
@@ -125,6 +126,52 @@ local function getBindComment(source)
     return table.concat(lines, '\n')
 end
 
+---@async
+local function packSee(see)
+    local name = see.name[1]
+    local buf  = {}
+    local target
+    for _, symbol in ipairs(wssymbol(name)) do
+        if symbol.name == name then
+            target = symbol.source
+            break
+        end
+    end
+    if target then
+        local row, col = guide.rowColOf(target.start)
+        buf[#buf+1] = ('[%s](%s#%d#%d)'):format(name, guide.getUri(target), row + 1, col)
+    else
+        buf[#buf+1] = ('~%s~'):format(name)
+    end
+    if see.comment then
+        buf[#buf+1] = ' '
+        buf[#buf+1] = see.comment.text
+    end
+    return table.concat(buf)
+end
+
+---@async
+local function lookUpDocSees(lines, docGroup)
+    local sees = {}
+    for _, doc in ipairs(docGroup) do
+        if doc.type == 'doc.see' then
+            sees[#sees+1] = doc
+        end
+    end
+    if #sees == 0 then
+        return
+    end
+    if #sees == 1 then
+        lines[#lines+1] = ('See: %s'):format(packSee(sees[1]))
+        return
+    end
+    lines[#lines+1] = 'See:'
+    for _, see in ipairs(sees) do
+        lines[#lines+1] = ('  * %s'):format(packSee(see))
+    end
+end
+
+---@async
 local function lookUpDocComments(source)
     local docGroup = source.bindDocs
     if not docGroup then
@@ -158,6 +205,7 @@ local function lookUpDocComments(source)
     if source.comment then
         lines[#lines+1] = normalizeComment(source.comment.text, uri)
     end
+    lookUpDocSees(lines, docGroup)
     if not lines or #lines == 0 then
         return nil
     end
@@ -352,6 +400,7 @@ local function getFunctionComment(source)
     return comment
 end
 
+---@async
 local function tryDocComment(source)
     local md = markdown()
     if source.value and source.value.type == 'function' then
@@ -379,6 +428,7 @@ local function tryDocComment(source)
     return result
 end
 
+---@async
 local function tryDocOverloadToComment(source)
     if source.type ~= 'doc.type.function' then
         return
@@ -457,6 +507,7 @@ local function tryDocEnum(source)
     return md:string()
 end
 
+---@async
 return function (source)
     if source.type == 'string' then
         return asString(source)

Diff for: script/core/hover/init.lua

@@ -6,6 +6,7 @@ local util       = require 'utility'
 local findSource = require 'core.find-source'
 local markdown   = require 'provider.markdown'
 local guide      = require 'parser.guide'
+local wssymbol   = require 'core.workspace-symbol'
 
 ---@async
 local function getHover(source)
@@ -14,6 +15,15 @@ local function getHover(source)
     local labelMark = {}
     local descMark  = {}
 
+    if source.type == 'doc.see.name' then
+        for _, symbol in ipairs(wssymbol(source[1])) do
+            if symbol.name == source[1] then
+                source = symbol.source
+                break
+            end
+        end
+    end
+
     ---@async
     local function addHover(def, checkLable, oop)
         if defMark[def] then
@@ -111,6 +121,7 @@ local accept = {
     ['doc.enum.name']  = true,
     ['function']       = true,
     ['doc.module']     = true,
+    ['doc.see.name']   = true,
 }
 
 ---@async

Diff for: script/parser/guide.lua

@@ -160,7 +160,7 @@ local childMap = {
     ['doc.type.field']     = {'name', 'extends'},
     ['doc.type.sign']      = {'node', '#signs'},
     ['doc.overload']       = {'overload', 'comment'},
-    ['doc.see']            = {'name'},
+    ['doc.see']            = {'name', 'comment'},
     ['doc.version']        = {'#versions'},
     ['doc.diagnostic']     = {'#names'},
     ['doc.as']             = {'as'},

Diff for: script/parser/luadoc.lua

@@ -1703,7 +1703,8 @@ local function bindDoc(source, binded)
         or doc.type == 'doc.private'
         or doc.type == 'doc.protected'
         or doc.type == 'doc.public'
-        or doc.type == 'doc.package' then
+        or doc.type == 'doc.package'
+        or doc.type == 'doc.see' then
             if source.type == 'function'
             or isParam then
                 goto CONTINUE

Diff for: test/crossfile/hover.lua

@@ -1644,3 +1644,40 @@ function f(x: number)
 function f(x: number, y: number)
 ```]]
 }
+
+TEST { {path = 'a.lua', content = [[
+---@class A
+
+---@see A # comment1
+local <?x?>
+]]},
+hover = [[
+```lua
+local x: unknown
+```
+
+---
+
+See: [A](file:///a.lua:1:10)  comment1]]
+}
+
+TEST { {path = 'a.lua', content = [[
+---@class A
+
+TTT = 1
+
+---@see A # comment1
+---@see TTT # comment2
+local <?x?>
+]]},
+hover = [[
+```lua
+local x: unknown
+```
+
+---
+
+See:
+  * [A](file:///a.lua:1:10)  comment1
+  * [TTT](file:///a.lua:3:0)  comment2]]
+}

Diff for: test/hover/init.lua

@@ -2393,3 +2393,13 @@ local x = obj[''].<?x?>()
 [[
 (field) A.x: fun():string
 ]]
+
+TEST [[
+---@class A
+---@field x number
+
+---@see <?A.x?>
+]]
+[[
+(field) A.x: number
+]]