Merge pull request #326 from uhziel/generic-name-string-literal

针对generic，类型参数允许是字符串字面值来表达类型

Author: sumneko

script/parser/guide.lua

@@ -99,6 +99,7 @@ m.childMap = {
  ['doc.vararg'] = {'vararg', 'comment'},
  ['doc.type.table'] = {'key', 'value', 'comment'},
  ['doc.type.function'] = {'#args', '#returns', 'comment'},
+ ['doc.type.typeliteral'] = {'node'},
  ['doc.overload'] = {'overload', 'comment'},
  ['doc.see'] = {'name', 'field'},
 }
@@ -1487,6 +1488,25 @@ function m.checkSameSimpleInSpecialBranch(status, obj, start, pushQueue)
  end
 end
 
+local function appendValidGenericType(results, status, typeName, obj)
+ if typeName.parent.type == 'doc.type.typeliteral' then
+ if obj.type == 'string' and status.interface.docType then
+ local docs = status.interface.docType(obj[1])
+ for i = 1, #docs do
+ local doc = docs[i]
+ if doc.type == 'doc.class.name'
+ or doc.type == 'doc.alias.name' then
+ results[#results+1] = doc
+ break
+ end
+ end
+ end
+ else
+ -- 发现没有使用 `T`，则沿用既有逻辑直接返回实参
+ results[#results+1] = obj
+ end
+end
+
 local function stepRefOfGeneric(status, typeUnit, args, mode)
  local results = {}
  if not args then
@@ -1511,7 +1531,7 @@ local function stepRefOfGeneric(status, typeUnit, args, mode)
  and source.parent.type == 'funcargs' then
  for index, arg in ipairs(source.parent) do
  if arg == source then
- results[#results+1] = args[index]
+ appendValidGenericType(results, status, typeName, args[index])
  end
  end
  end

script/parser/luadoc.lua

@@ -56,6 +56,7 @@ Symbol <- ({} {
  / '...'
  / '+'
  / '#'
+ / '`'
  } {})
  -> Symbol
 ]], {
@@ -450,12 +451,41 @@ function parseType(parent)
  if not tp then
  break
  end
+
+ -- 处理 `T` 的情况
+ local typeLiteral = nil
+ if tp == 'symbol' and content == '`' then
+ nextToken()
+ if not checkToken('symbol', '`', 2) then
+ break
+ end
+ tp, content = peekToken()
+ if not tp then
+ break
+ end
+ -- TypeLiteral，指代类型的字面值。比如，对于类 Cat 来说，它的 TypeLiteral 是 "Cat"
+ typeLiteral = {
+ type = 'doc.type.typeliteral',
+ parent = result,
+ start = getStart(),
+ finish = nil,
+ node = nil,
+ }
+ end
+
  if tp == 'name' then
  nextToken()
  local typeUnit = parseTypeUnit(result, content)
  if not typeUnit then
  break
  end
+ if typeLiteral then
+ nextToken()
+ typeLiteral.finish = getFinish()
+ typeLiteral.node = typeUnit
+ typeUnit.parent = typeLiteral
+ typeUnit = typeLiteral
+ end
  result.types[#result.types+1] = typeUnit
  if not result.start then
  result.start = typeUnit.start

test/definition/luadoc.lua

@@ -197,3 +197,59 @@ TEST [[
  ---@type Cat
  local <?<!v!>?>
 ]]
+
+TEST [[
+---@class Foo
+local Foo = {}
+function Foo:<!bar1!>() end
+
+---@generic T
+---@param arg1 T
+---@return T
+function Generic(arg1) print(arg1) end
+
+local v1 = Generic(Foo)
+print(v1.<?bar1?>)
+]]
+
+TEST [[
+---@class Foo
+local Foo = {}
+function Foo:bar1() end
+
+---@generic T
+---@param arg1 T
+---@return T
+function Generic(arg1) print(arg1) end
+
+local v1 = Generic("Foo")
+print(v1.<?bar1?>)
+]]
+
+TEST [[
+---@class Foo
+local Foo = {}
+function Foo:bar1() end
+
+---@generic T
+---@param arg1 `T`
+---@return T
+function Generic(arg1) print(arg1) end
+
+local v1 = Generic(Foo)
+print(v1.<?bar1?>)
+]]
+
+TEST [[
+---@class Foo
+local Foo = {}
+function Foo:<!bar1!>() end
+
+---@generic T
+---@param arg1 `T`
+---@return T
+function Generic(arg1) print(arg1) end
+
+local v1 = Generic("Foo")
+print(v1.<?bar1?>)
+]]