player_doc (#93)

增加了player.lua文档的注释

lua/core/player.lua

@@ -93,9 +93,10 @@ function Player:initialize()
   self.fixedDistance = {}
 end
 
----@param general General
+--- 设置角色、体力、技能。
----@param setHp boolean
+---@param general General @ 角色类型
----@param addSkills boolean
+---@param setHp boolean @ 是否设置体力
+---@param addSkills boolean @ 是否增加技能
 function Player:setGeneral(general, setHp, addSkills)
   self.general = general
   if setHp then
@@ -108,12 +109,14 @@ function Player:setGeneral(general, setHp, addSkills)
   end
 end
 
----@param flag string
+--- 查询角色是否存在flag。
+---@param flag string @ 一种标记
 function Player:hasFlag(flag)
   return table.contains(self.flag, flag)
 end
 
----@param flag string
+--- 为角色赋予flag。
+---@param flag string @ 一种标记
 function Player:setFlag(flag)
   if flag == "." then
     self:clearFlags()
@@ -129,10 +132,14 @@ function Player:setFlag(flag)
   end
 end
 
+--- 清除角色flag。
 function Player:clearFlags()
   self.flag = {}
 end
 
+--- 为角色赋予Mark。
+---@param mark string @ 标记
+---@param count integer @ 为标记赋予的数量
 -- mark name and UI:
 -- 'xxx': invisible mark
 -- '@mark': mark with extra data (maybe string or number)
@@ -144,6 +151,9 @@ function Player:addMark(mark, count)
   self:setMark(mark, math.max(num + count, 0))
 end
 
+--- 为角色移除Mark。
+---@param mark string @ 标记
+---@param count integer @ 为标记删除的数量
 function Player:removeMark(mark, count)
   count = count or 1
   local num = self.mark[mark]
@@ -151,16 +161,23 @@ function Player:removeMark(mark, count)
   self:setMark(mark, math.max(num - count, 0))
 end
 
+--- 为角色设置Mark至指定数量。
+---@param mark string @ 标记
+---@param count integer @ 为标记删除的数量
 function Player:setMark(mark, count)
   if self.mark[mark] ~= count then
     self.mark[mark] = count
   end
 end
 
+--- 获取角色对应Mark的数量。
+---@param mark string @ 标记
+---@param count integer @ 为标记删除的数量
 function Player:getMark(mark)
   return (self.mark[mark] or 0)
 end
 
+--- 获取角色有哪些Mark。
 function Player:getMarkNames()
   local ret = {}
   for k, _ in pairs(self.mark) do
@@ -169,9 +186,10 @@ function Player:getMarkNames()
   return ret
 end
 
----@param playerArea PlayerCardArea
+--- 将指定数量的牌加入玩家的对应区域。
----@param cardIds integer[]
+---@param playerArea PlayerCardArea @ 玩家牌所在的区域
----@param specialName string
+---@param cardIds integer[] @ 牌的ID，返回唯一牌
+---@param specialName string @ 私人牌堆名
 function Player:addCards(playerArea, cardIds, specialName)
   assert(table.contains({ Player.Hand, Player.Equip, Player.Judge, Player.Special }, playerArea))
   assert(playerArea ~= Player.Special or type(specialName) == "string")
@@ -184,9 +202,10 @@ function Player:addCards(playerArea, cardIds, specialName)
   end
 end
 
----@param playerArea PlayerCardArea
+--- 将指定数量的牌移除出玩家的对应区域。
----@param cardIds integer[]
+---@param playerArea PlayerCardArea @ 玩家牌所在的区域
----@param specialName string
+---@param cardIds integer[] @ 牌的ID，返回唯一牌
+---@param specialName string @ 私人牌堆名
 function Player:removeCards(playerArea, cardIds, specialName)
   assert(table.contains({ Player.Hand, Player.Equip, Player.Judge, Player.Special }, playerArea))
   assert(playerArea ~= Player.Special or type(specialName) == "string")
@@ -205,13 +224,15 @@ end
 
 -- virtual delayed trick can use these functions too
 
----@param card Card
+--- 为玩家提供虚拟装备。
+---@param card Card @ 卡牌
 function Player:addVirtualEquip(card)
   assert(card and card:isInstanceOf(Card) and card:isVirtual())
   table.insertIfNeed(self.virtual_equips, card)
 end
 
----@param cid integer
+--- 为玩家移除虚拟装备。
+---@param cid integer @ 卡牌ID，用来定位装备
 function Player:removeVirtualEquip(cid)
   for _, c in ipairs(self.virtual_equips) do
     for _, id in ipairs(c.subcards) do
@@ -223,7 +244,8 @@ function Player:removeVirtualEquip(cid)
   end
 end
 
----@param cid integer
+--- 确认玩家是否存在虚拟装备。
+---@param cid integer @ 卡牌ID，用来定位装备
 function Player:getVirualEquip(cid)
   for _, c in ipairs(self.virtual_equips) do
     for _, id in ipairs(c.subcards) do
@@ -234,6 +256,7 @@ function Player:getVirualEquip(cid)
   end
 end
 
+--- 确认玩家判定区是否存在延迟锦囊牌。
 function Player:hasDelayedTrick(card_name)
   for _, id in ipairs(self:getCardIds(Player.Judge)) do
     local c = self:getVirualEquip(id)
@@ -244,9 +267,10 @@ function Player:hasDelayedTrick(card_name)
   end
 end
 
----@param playerAreas PlayerCardArea
+--- 获取玩家特定区域所有牌的ID。
----@param specialName string
+---@param playerAreas PlayerCardArea @ 玩家牌所在的区域
----@return integer[]
+---@param specialName string @私人牌堆名
+---@return integer[] @ 返回对应区域的所有牌对应的ID
 function Player:getCardIds(playerAreas, specialName)
   local rightAreas = { Player.Hand, Player.Equip, Player.Judge }
   playerAreas = playerAreas or rightAreas
@@ -265,12 +289,14 @@ function Player:getCardIds(playerAreas, specialName)
   return cardIds
 end
 
----@param name string
+--- 通过名字检索获取玩家是否存在对应私人牌堆。
+---@param name string @ 私人牌堆名
 function Player:getPile(name)
   return self.special_cards[name] or {}
 end
 
----@param id integer
+--- 通过ID检索获取玩家是否存在对应私人牌堆。
+---@param id integer @ 私人牌堆ID
 ---@return string|null
 function Player:getPileNameOfId(id)
   for k, v in pairs(self.special_cards) do
@@ -283,8 +309,9 @@ function Player:getHandcardNum()
   return #self:getCardIds(Player.Hand)
 end
 
----@param cardSubtype CardSubtype
+--- 检索玩家装备区是否存在对应类型的装备。
----@return integer|null
+---@param cardSubtype CardSubtype @ 卡牌子类
+---@return integer|null @ 返回卡牌ID或nil
 function Player:getEquipment(cardSubtype)
   for _, cardId in ipairs(self.player_cards[Player.Equip]) do
     if Fk:getCardById(cardId).sub_type == cardSubtype then
@@ -295,6 +322,7 @@ function Player:getEquipment(cardSubtype)
   return nil
 end
 
+--- 获取玩家手牌上限。
 function Player:getMaxCards()
   local baseValue = math.max(self.hp, 0)
 
@@ -317,6 +345,7 @@ function Player:getMaxCards()
   return math.max(baseValue, 0)
 end
 
+--- 获取玩家攻击距离。
 function Player:getAttackRange()
   local weapon = Fk:getCardById(self:getEquipment(Card.SubtypeWeapon))
   local baseAttackRange = math.max(weapon and weapon.attack_range or 1, 0)
@@ -324,18 +353,23 @@ function Player:getAttackRange()
   return math.max(baseAttackRange, 0)
 end
 
----@param other Player
+--- 修改玩家与其他角色的固定距离。
----@param num integer
+---@param other Player @ 其他玩家
+---@param num integer @ 距离数
 function Player:setFixedDistance(other, num)
   self.fixedDistance[other] = num
 end
 
----@param other Player
+--- 移除玩家与其他角色的固定距离。
+---@param other Player @ 其他玩家
 function Player:removeFixedDistance(other)
   self.fixedDistance[other] = nil
 end
 
----@param other Player
+--- 获取玩家与其他角色的实际距离。
+---
+--- 通过 二者位次+距离技能之和 与 两者间固定距离 进行对比，更大的为实际距离。
+---@param other Player @ 其他玩家
 function Player:distanceTo(other)
   assert(other:isInstanceOf(Player))
   local right = 0
@@ -363,7 +397,8 @@ function Player:distanceTo(other)
   return math.max(ret, 1)
 end
 
----@param other Player
+--- 获取其他玩家是否在玩家的攻击距离内。
+---@param other Player @ 其他玩家
 function Player:inMyAttackRange(other)
   if self == other then
     return false
@@ -377,6 +412,9 @@ function Player:inMyAttackRange(other)
   return self:distanceTo(other) <= baseAttackRange
 end
 
+--- 增加玩家使用特定牌的历史次数。
+---@param cardName string @ 牌名
+---@param num integer @ 次数
 function Player:addCardUseHistory(cardName, num)
   num = num or 1
   assert(type(num) == "number" and num ~= 0)
@@ -388,6 +426,10 @@ function Player:addCardUseHistory(cardName, num)
   end
 end
 
+--- 设定玩家使用特定牌的历史次数。
+---@param cardName string @ 牌名
+---@param num integer @ 次数
+---@param scope integer @ 查询历史范围
 function Player:setCardUseHistory(cardName, num, scope)
   if cardName == "" and num == nil and scope == nil then
     self.cardUsedHistory = {}
@@ -407,6 +449,9 @@ function Player:setCardUseHistory(cardName, num, scope)
   end
 end
 
+--- 增加玩家使用特定技能的历史次数。
+---@param skill_name string @ 技能名
+---@param num integer @ 次数
 function Player:addSkillUseHistory(skill_name, num)
   num = num or 1
   assert(type(num) == "number" and num ~= 0)
@@ -418,6 +463,10 @@ function Player:addSkillUseHistory(skill_name, num)
   end
 end
 
+--- 设定玩家使用特定技能的历史次数。
+---@param skill_name string @ 技能名
+---@param num integer @ 次数
+---@param scope integer @ 查询历史范围
 function Player:setSkillUseHistory(skill_name, num, scope)
   if skill_name == "" and num == nil and scope == nil then
     self.skillUsedHistory = {}
@@ -437,6 +486,9 @@ function Player:setSkillUseHistory(skill_name, num, scope)
   end
 end
 
+--- 获取玩家使用特定牌的历史次数。
+---@param cardName string @ 牌名
+---@param scope integer @ 查询历史范围
 function Player:usedCardTimes(cardName, scope)
   if not self.cardUsedHistory[cardName] then
     return 0
@@ -445,6 +497,9 @@ function Player:usedCardTimes(cardName, scope)
   return self.cardUsedHistory[cardName][scope]
 end
 
+--- 获取玩家使用特定技能的历史次数。
+---@param skill_name string @ 技能名
+---@param scope integer @ 查询历史范围
 function Player:usedSkillTimes(cardName, scope)
   if not self.skillUsedHistory[cardName] then
     return 0
@@ -453,22 +508,27 @@ function Player:usedSkillTimes(cardName, scope)
   return self.skillUsedHistory[cardName][scope]
 end
 
+--- 获取玩家是否无手牌。
 function Player:isKongcheng()
   return #self:getCardIds(Player.Hand) == 0
 end
 
+--- 获取玩家是否无手牌及装备牌。
 function Player:isNude()
   return #self:getCardIds{Player.Hand, Player.Equip} == 0
 end
 
+--- 获取玩家所有区域是否无牌。
 function Player:isAllNude()
   return #self:getCardIds() == 0
 end
 
+--- 获取玩家是否受伤。
 function Player:isWounded()
   return self.hp < self.maxHp
 end
 
+--- 获取玩家已失去体力。
 function Player:getLostHp()
   return math.min(self.maxHp - self.hp, self.maxHp)
 end
@@ -483,7 +543,10 @@ local function getActualSkill(skill)
   return skill
 end
 
----@param skill string | Skill
+--- 检索玩家是否有对应技能。
+---@param skill string | Skill @ 技能名
+---@param ignoreNullified boolean @ 忽略技能是否被无效
+---@param ignoreAlive boolean @ 忽略角色在场与否
 function Player:hasSkill(skill, ignoreNullified, ignoreAlive)
   if not ignoreAlive and self.dead then
     return false
@@ -508,8 +571,9 @@ function Player:hasSkill(skill, ignoreNullified, ignoreAlive)
   return false
 end
 
----@param skill string | Skill
+--- 为玩家增加对应技能。
----@param source_skill string | Skill | nil
+---@param skill string | Skill @ 技能名
+---@param source_skill string | Skill | nil @ 本有技能（和衍生技能相对）
 ---@return Skill[] @ got skills that Player didn't have at start
 function Player:addSkill(skill, source_skill)
   skill = getActualSkill(skill)
@@ -553,8 +617,9 @@ function Player:addSkill(skill, source_skill)
   return ret
 end
 
----@param skill string | Skill
+--- 为玩家删除对应技能。
----@param source_skill string | Skill | nil
+---@param skill string | Skill @ 技能名
+---@param source_skill string | Skill | nil @ 本有技能（和衍生技能相对）
 ---@return Skill[] @ lost skills that the Player doesn't have anymore
 function Player:loseSkill(skill, source_skill)
   skill = getActualSkill(skill)
@@ -583,6 +648,7 @@ function Player:loseSkill(skill, source_skill)
   return ret
 end
 
+--- 获取对应玩家所有技能。
 -- return all skills that xxx:hasSkill() == true
 function Player:getAllSkills()
   local ret = {table.unpack(self.player_skills)}