player_doc更新 (#168)

更新文档注释，还请各位查阅。

Co-authored-by: YWSC120 <111111@163.com>

lua/core/card.lua

@@ -16,13 +16,13 @@
 ---@field public sub_type CardSubtype @ 卡牌的子种类（例如延时锦囊牌、武器、防具等）
 ---@field public area CardArea @ 卡牌所在区域（例如手牌区，判定区，装备区，牌堆，弃牌堆···）
 ---@field public mark table<string, integer> @ 当前拥有的所有标记，用烂了
----@field public subcards integer[]
----@field public skillName string @ for virtual cards
----@field public skillNames string[]
----@field public skill Skill
----@field public special_skills string[] | nil
----@field public is_damage_card boolean
----@field public is_derived boolean|null
+---@field public subcards integer[] @ 子卡ID表
+---@field public skillName string @ 虚拟牌的技能名 for virtual cards
+---@field public skillNames string[] @ 虚拟牌的技能名们（一张虚拟牌可能有多个技能名，如芳魂、龙胆、朱雀羽扇）
+---@field public skill Skill @ 技能（用于实现卡牌效果）
+---@field public special_skills string[] | nil @ 衍生技能，如重铸
+---@field public is_damage_card boolean @ 是否为会造成伤害的牌
+---@field public is_derived boolean|null @ 判断是否为衍生牌
 local Card = class("Card")
 
 ---@alias Suit integer
@@ -336,9 +336,10 @@ function Card:getMarkNames()
   return ret
 end
 
----@param anotherCard Card
----@param diff boolean
----@return boolean
+--- 比较两张卡牌的花色是否相同
+---@param anotherCard Card @ 另一张卡牌
+---@param diff boolean @ 比较二者相同还是不同
+---@return boolean 返回比较结果
 function Card:compareSuitWith(anotherCard, diff)
   if self ~= anotherCard and table.contains({ self.suit, anotherCard.suit }, Card.NoSuit) then
     return false
@@ -351,9 +352,10 @@ function Card:compareSuitWith(anotherCard, diff)
   end
 end
 
----@param anotherCard Card
----@param diff boolean
----@return boolean
+--- 比较两张卡牌的颜色是否相同
+---@param anotherCard Card @ 另一张卡牌
+---@param diff boolean @ 比较二者相同还是不同
+---@return boolean 返回比较结果
 function Card:compareColorWith(anotherCard, diff)
   if self ~= anotherCard and table.contains({ self.color, anotherCard.color }, Card.NoColor) then
     return false
@@ -366,9 +368,10 @@ function Card:compareColorWith(anotherCard, diff)
   end
 end
 
----@param anotherCard Card
----@param diff boolean
----@return boolean
+--- 比较两张卡牌的点数是否相同
+---@param anotherCard Card @ 另一张卡牌
+---@param diff boolean @ 比较二者相同还是不同
+---@return boolean 返回比较结果
 function Card:compareNumberWith(anotherCard, diff)
   if self ~= anotherCard and self.number < 1 or anotherCard.number < 1 then
     return false

lua/core/engine.lua

@@ -20,8 +20,8 @@
 ---@field public translations table<string, table<string, string>> @ 翻译表
 ---@field public game_modes table<string, GameMode> @ 所有游戏模式
 ---@field public disabled_packs string[] @ 禁用的拓展包列表
----@field public currentResponsePattern string
----@field public currentResponseReason string
+---@field public currentResponsePattern string @ 要求用牌的种类（如要求用特定花色的桃···）
+---@field public currentResponseReason string @ 要求用牌的原因（如濒死，被特定牌指定，使用特定技能···）
 local Engine = class("Engine")
 
 --- Engine的构造函数。

lua/core/general.lua

@@ -82,6 +82,7 @@ function General:addRelatedSkill(skill)
   end
 end
 
+--- 获取武将所有技能。
 function General:getSkillNameList(include_lord)
   local ret = table.map(self.skills, Util.NameMapper)
   table.insertTable(ret, self.other_skills)

lua/core/player.lua

@@ -692,8 +692,9 @@ function Player:getAllSkills()
   return ret
 end
 
----@param to Player
----@param card Card
+--- 确认玩家是否可以对特定玩家使用特定牌。
+---@param to Player @ 特定玩家
+---@param card Card @ 特定牌
 function Player:isProhibited(to, card)
   local r = Fk:currentRoom()
   local status_skills = r.status_skills[ProhibitSkill] or {}
@@ -705,7 +706,8 @@ function Player:isProhibited(to, card)
   return false
 end
 
----@param card Card
+--- 确认玩家是否可以使用特定牌。
+---@param card Card @ 特定的牌
 function Player:prohibitUse(card)
   local status_skills = Fk:currentRoom().status_skills[ProhibitSkill] or {}
   for _, skill in ipairs(status_skills) do
@@ -716,7 +718,8 @@ function Player:prohibitUse(card)
   return false
 end
 
----@param card Card
+--- 确认玩家是否可以打出特定牌。
+---@param card Card @ 特定的牌
 function Player:prohibitResponse(card)
   local status_skills = Fk:currentRoom().status_skills[ProhibitSkill] or {}
   for _, skill in ipairs(status_skills) do
@@ -727,7 +730,8 @@ function Player:prohibitResponse(card)
   return false
 end
 
----@param card Card
+--- 确认玩家是否可以弃置特定牌。
+---@param card Card @ 特定的牌
 function Player:prohibitDiscard(card)
   local status_skills = Fk:currentRoom().status_skills[ProhibitSkill] or {}
   for _, skill in ipairs(status_skills) do
@@ -743,8 +747,9 @@ fk.SwitchYang = 0
 ---@field SwitchYin number @ 转换技状态阴
 fk.SwitchYin = 1
 
----@param skillName string
----@return number
+--- 获取转换技状态
+---@param skillName string @ 技能名
+---@return number @ 转换技状态
 function Player:getSwitchSkillState(skillName, afterUse)
   if afterUse then
     return self:getMark(MarkEnum.SwithSkillPreName .. skillName) < 1 and fk.SwitchYin or fk.SwitchYang

lua/core/skill.lua

@@ -12,7 +12,7 @@
 ---@field public anim_type string @ 技能类型定义
 ---@field public related_skills Skill[] @ 和本技能相关的其他技能，有时候一个技能实际上是通过好几个技能拼接而实现的。
 ---@field public attached_equip string @ 属于什么装备的技能？
----@field public switchSkillName string
+---@field public switchSkillName string @ 转换技名字
 local Skill = class("Skill")
 
 ---@alias Frequency integer
@@ -88,10 +88,13 @@ function Skill:isEffectable(player)
   return true
 end
 
+--- 为技能增加所属势力，需要在隶属特定势力时才能使用此技能。
+--- 案例：手杀文鸯
 function Skill:addAttachedKingdom(kingdom)
   table.insertIfNeed(self.attachedKingdom, kingdom)
 end
 
+--- 判断某个技能是否为转换技
 function Skill:isSwitchSkill()
   return self.switchSkillName and type(self.switchSkillName) == 'string' and self.switchSkillName ~= ""
 end