From 02dd5b6557d3e70859bc3ddb234f8924b0166221 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9C=80=E8=90=8C=E5=B0=8F=E6=B1=90?= Date: Wed, 2 Nov 2022 19:20:22 +0800 Subject: [PATCH] improve `---@see` resolve #1344 --- changelog.md | 2 ++ script/core/hover/description.lua | 51 +++++++++++++++++++++++++++++++ script/core/hover/init.lua | 11 +++++++ script/parser/guide.lua | 2 +- script/parser/luadoc.lua | 3 +- test/crossfile/hover.lua | 37 ++++++++++++++++++++++ test/hover/init.lua | 10 ++++++ 7 files changed, 114 insertions(+), 2 deletions(-) diff --git a/changelog.md b/changelog.md index 07f0bc5c7..a8d25258c 100644 --- a/changelog.md +++ b/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 --git a/script/core/hover/description.lua b/script/core/hover/description.lua index f8b0694db..0bbe510ab 100644 --- a/script/core/hover/description.lua +++ b/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 --git a/script/core/hover/init.lua b/script/core/hover/init.lua index 61f094559..2051623c7 100644 --- a/script/core/hover/init.lua +++ b/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 --git a/script/parser/guide.lua b/script/parser/guide.lua index abc82375f..b22c55f05 100644 --- a/script/parser/guide.lua +++ b/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 --git a/script/parser/luadoc.lua b/script/parser/luadoc.lua index 4b2376a38..f849ecb9c 100644 --- a/script/parser/luadoc.lua +++ b/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 --git a/test/crossfile/hover.lua b/test/crossfile/hover.lua index 6d1f3df6d..4a567a319 100644 --- a/test/crossfile/hover.lua +++ b/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 +]]}, +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 +]]}, +hover = [[ +```lua +local x: unknown +``` + +--- + +See: + * [A](file:///a.lua:1:10) comment1 + * [TTT](file:///a.lua:3:0) comment2]] +} diff --git a/test/hover/init.lua b/test/hover/init.lua index dad32f14b..780c1da89 100644 --- a/test/hover/init.lua +++ b/test/hover/init.lua @@ -2393,3 +2393,13 @@ local x = obj[''].() [[ (field) A.x: fun():string ]] + +TEST [[ +---@class A +---@field x number + +---@see +]] +[[ +(field) A.x: number +]]