注释优化

huahua132 · Jan 13, 2025 · baf23e2 · baf23e2
1 parent 93abd43
commit baf23e2
Show file tree

Hide file tree

Showing 14 changed files with 518 additions and 298 deletions.
diff --git a/lualib/skynet-fly/log.lua b/lualib/skynet-fly/log.lua
@@ -1,6 +1,5 @@
 local skynet = require "skynet"
 local table_util = require "skynet-fly.utils.table_util"
-local time_util = require "skynet-fly.utils.time_util"
 local module_info = require "skynet-fly.etc.module_info"
 local sformat = string.format
 local sdump = table_util.dump
@@ -11,14 +10,10 @@ local pairs = pairs
 local assert = assert
 local tostring = tostring
 local tinsert = table.insert
-local ipairs = ipairs
 local sfind = string.find
 local ssub = string.sub
 local schar = string.char
-local math_floor = math.floor
 local tpack = table.pack
-local tunpack = table.unpack
-local osdate = os.date
 
 local M = {
 	INFO = 0,
@@ -125,8 +120,8 @@ function M.parse(log_str)
 		if schar(log_str:byte(34)) == '[' then
 			local _,type_e = sfind(log_str,"]",38,true)
 			if type_e then
-				log_type = ssub(log_str,35,type_e - 1)
-				log_type = level_map[log_type] or M.UNKNOWN
+				local log_type_str = ssub(log_str,35,type_e - 1)
+				log_type = level_map[log_type_str] or M.UNKNOWN
 
 				local s_n_b = type_e + 2
 				local _,s_n_e = sfind(log_str,"]",s_n_b,true)

diff --git a/lualib/skynet-fly/logrotate.lua b/lualib/skynet-fly/logrotate.lua
@@ -1,3 +1,12 @@
+---#API
+---#content ---
+---#content title: 日志轮换
+---#content date: 2024-06-29 22:00:00
+---#content categories: ["skynet_fly API 文档","日志轮换"]
+---#content category_bar: true
+---#content tags: [skynet_fly_api]
+---#content ---
+---#content [logrotate](https://github.com/huahua132/skynet_fly/blob/master/lualib/skynet-fly/logrotate.lua)
 local contriner_client = require "skynet-fly.client.contriner_client"
 local skynet_util = require "skynet-fly.utils.skynet_util"
 local contriner_interface = require "skynet-fly.contriner.contriner_interface"
@@ -35,7 +44,9 @@ end
 
 local M = {}
 local mt = {__index = M}
-
+---#desc 新建对象
+---@param filename string 文件名
+---@return table 对象
 function M:new(filename)
     local t = {
         cfg = {
@@ -47,7 +58,9 @@ function M:new(filename)
     return t
 end
 
---重命名文件格式
+---#desc 重命名文件格式
+---@param rename_format string
+---@return table 对象
 function M:set_rename_format(rename_format)
     assert(not self.is_builder, "builded can`t use set_rename_format")
     assert(type(rename_format) == 'string', "rename_format not string")
@@ -56,7 +69,9 @@ function M:set_rename_format(rename_format)
     return self
 end
 
---设置文件路径
+---#desc 设置文件路径
+---@param file_path string 文件路径
+---@return table 对象
 function M:set_file_path(file_path)
     assert(not self.is_builder, "builded can`t use set_file_path")
     assert(type(file_path) == 'string', "file_path not string")
@@ -65,7 +80,9 @@ function M:set_file_path(file_path)
     return self
 end
 
---设置至少多大才会切割
+---#desc 设置至少多大才会切割
+---@param limit_size number 至少多大
+---@return table 对象
 function M:set_limit_size(limit_size)
     assert(not self.is_builder, "builded can`t use set_limit_size")
     assert(type(limit_size) == 'number', "limit_size not number")
@@ -75,7 +92,9 @@ function M:set_limit_size(limit_size)
     return self
 end
 
---设置最大保留天数
+---#desc 设置最大保留天数
+---@param max_age number 保留天数
+---@return table 对象
 function M:set_max_age(max_age)
     assert(not self.is_builder, "builded can`t use set_max_age")
     assert(type(max_age) == 'number', "max_age not number")
@@ -85,7 +104,9 @@ function M:set_max_age(max_age)
     return self
 end
 
---设置最大保留文件数
+---#desc 设置最大保留文件数
+---@param max_backups number 保留文件数
+---@return table 对象
 function M:set_max_backups(max_backups)
     assert(not self.is_builder, "builded can`t use set_max_backups")
     assert(type(max_backups) == 'number', "max_backups not number")
@@ -95,7 +116,9 @@ function M:set_max_backups(max_backups)
     return self
 end
 
---设置轮转时调用系统命令
+---#desc 设置轮转时调用系统命令
+---@param sys_cmd string 系统命令
+---@return table 对象
 function M:set_sys_cmd(sys_cmd)
     assert(not self.is_builder, "builded can`t use set_sys_cmd")
     assert(type(sys_cmd == 'string'), "sys_cmd not number")
@@ -104,93 +127,75 @@ function M:set_sys_cmd(sys_cmd)
     return self
 end
 
---设置整点报时类型
+---#desc 设置整点报时类型
+---@param point_type number 报时类型
+---@return table 对象
 function M:set_point_type(point_type)
     assert(not self.is_builder, "builded can`t use set_point_type")
     assert(type(point_type == 'number'), "point_type not number")
     local cfg = self.cfg
     cfg.point_type = point_type
     return self
 end
---[[
-    函数作用域：M:new 对象的成员函数
-	函数名称：set_month
-	描述:  指定几月
-	参数:
-		- month (number): 月份 1-12
-    
-]]
+
+---#desc 指定几月
+---@param month number 几月[1,12]
+---@return table 对象
 function M:set_month(month)
     assert(not self.is_builder, "builded can`t use set_month")
-    assert(month >= 1 and month <= 12)
+    assert(month >= 1 and month <= 12, "Must be within this range[1,12] month=" .. tostring(month))
     local cfg = self.cfg
     cfg.month = month
     return self
 end
---[[
-    函数作用域：M:new 对象的成员函数
-	函数名称：set_day
-	描述:  每月第几天,超过适配到最后一天
-	参数:
-		- day (number): 天数 1-31
-]]
+
+---#desc 指定月第几天
+---@param day number 月第几天[1,31]
+---@return table 对象
 function M:set_day(day)
     assert(not self.is_builder, "builded can`t use set_day")
-    assert(day >= 1 and day <= 31)
+    assert(day >= 1 and day <= 31, "Must be within this range[1,31] day=" .. tostring(day))
     local cfg = self.cfg
     cfg.day = day
     return self
 end
---[[
-    函数作用域：M:new 对象的成员函数
-	函数名称：set_hour
-	描述:  几时
-	参数:
-		- hour (number): 几时 0-23
-]]
+
+---#desc 几时
+---@param hour number 几时[0,23]
+---@return table 对象
 function M:set_hour(hour)
     assert(not self.is_builder, "builded can`t use set_hour")
-    assert(hour >= 0 and hour <= 23)
+    assert(hour >= 0 and hour <= 23, "Must be within this range[0,23] hour=" .. tostring(hour))
     local cfg = self.cfg
     cfg.hour = hour
     return self
 end
---[[
-    函数作用域：M:new 对象的成员函数
-	函数名称：set_min
-	描述:  几分
-	参数:
-		- min (number): 几分 0-59
-]]
+
+---#desc 几分
+---@param min number 几分[0,59]
+---@return table 对象
 function M:set_min(min)
     assert(not self.is_builder, "builded can`t use set_min")
-    assert(min >= 0 and min <= 59)
+    assert(min >= 0 and min <= 59, "Must be within this range[0,59] min=" .. tostring(min))
     local cfg = self.cfg
     cfg.min = min
     return self
 end
---[[
-    函数作用域：M:new 对象的成员函数
-	函数名称：set_sec
-	描述:  几秒
-	参数:
-		- sec (number): 几秒 0-59
-]]
+
+---#desc 几秒
+---@param sec number 几秒[0,59]
+---@return table 对象
 function M:set_sec(sec)
     assert(not self.is_builder, "builded can`t use set_sec")
-    assert(sec >= 0 and sec <= 59)
+    assert(sec >= 0 and sec <= 59, "Must be within this range[0,59] sec=" .. tostring(sec))
     local cfg = self.cfg
     cfg.sec = sec
     return self
 end
 
---[[
-    函数作用域：M:new 对象的成员函数
-	函数名称：set_wday
-	描述:  周几（仅仅设置每周有效）
-	参数:
-		- wday (number): 周几 1-7 星期天为 1
-]]
+---#desc 周几（仅仅设置每周有效）
+---@param wday number 周几[1,7]
+---@return table 对象
 function M:set_wday(wday)
     assert(not self.is_builder, "builded can`t use set_wday")
     assert(wday >= 1 and wday <= 7)
@@ -199,13 +204,9 @@ function M:set_wday(wday)
     return self
 end
 
---[[
-    函数作用域：M:new 对象的成员函数
-	函数名称：set_yday
-	描述:  一年第几天（仅仅设置每年第几天有效）
-	参数:
-		- yday (number): 第几天 1-366 超过适配到最后一天。
-]]
+---#desc 一年第几天（仅仅设置每年第几天有效）
+---@param yday number 周几[1,366]
+---@return table 对象
 function M:set_yday(yday)
     assert(not self.is_builder, "builded can`t use set_yday")
     assert(yday >= 1 and yday <= 366)
@@ -214,7 +215,9 @@ function M:set_yday(yday)
     return self
 end
 
---设置保留文件整理匹配表达式
+---#desc 设置保留文件整理匹配表达式
+---@param back_pattern string find表达式
+---@return table 对象
 function M:set_back_pattern(back_pattern)
     assert(not self.is_builder, "builded can`t use set_back_pattern")
     assert(type(back_pattern) == 'string', "back_pattern not string")
@@ -223,7 +226,8 @@ function M:set_back_pattern(back_pattern)
     return self
 end
 
---构建轮转
+---#desc 构建轮转
+---@return table 对象
 function M:builder()
     assert(not self.is_builder, "builded can`t use builder")
     self.is_builder = true
@@ -234,7 +238,8 @@ function M:builder()
     return self
 end
 
---取消轮转
+---#desc 取消轮转
+---@return table 对象
 function M:cancel()
     assert(self.is_builder, "not builder can`t use cancel")
     contriner_client:instance("logrotate_m"):mod_call("cancel", skynet.self(), self.id)

diff --git a/lualib/skynet-fly/mod_queue.lua b/lualib/skynet-fly/mod_queue.lua
@@ -1,3 +1,12 @@
+---#API
+---#content ---
+---#content title: mod映射队列
+---#content date: 2024-06-29 22:00:00
+---#content categories: ["skynet_fly API 文档","执行队列"]
+---#content category_bar: true
+---#content tags: [skynet_fly_api]
+---#content ---
+---#content [mod_queue](https://github.com/huahua132/skynet_fly/blob/master/lualib/skynet-fly/mod_queue.lua)
 local queue = require "skynet.queue"
 
 local setmetatable = setmetatable
@@ -6,6 +15,9 @@ local assert = assert
 local M = {}
 local mata = {__index = M}
 
+---#desc 新建队列对象
+---@param cap number 容量
+---@return table
 function M:new(cap)
     assert(cap > 0)
     local t = {
@@ -21,6 +33,11 @@ function M:new(cap)
     return t
 end
 
+---#desc 执行函数
+---@param mod_num number mod_num % cap + 1 决定使用队列
+---@param func function 执行函数
+---@param ... any 函数参数
+---@return ... 函数返回值
 function M:exec(mod_num, func, ...)
     local index = mod_num % self.cap + 1
     local queue = self.queue_list[index]

diff --git a/lualib/skynet-fly/mult_queue.lua b/lualib/skynet-fly/mult_queue.lua
@@ -1,8 +1,16 @@
---[[
-    这是一个并发，单发互斥的队列
-    并发: key不同不用排队，key相同排队执行，不同key不用排队，有单发执行中，需等待
-    单发: 单发顺序执行需要排队，有并发执行中，需等待
-]]
+---#API
+---#content ---
+---#content title: 并发，单发互斥的队列
+---#content date: 2024-06-29 22:00:00
+---#content categories: ["skynet_fly API 文档","执行队列"]
+---#content category_bar: true
+---#content tags: [skynet_fly_api]
+---#content ---
+---#content [mult_queue](https://github.com/huahua132/skynet_fly/blob/master/lualib/skynet-fly/mult_queue.lua)
+
+---#content这是一个并发，单发互斥的队列
+---#content并发: key不同不用排队，key相同排队执行，不同key不用排队，有单发执行中，需等待
+---#content单发: 单发顺序执行需要排队，有并发执行中，需等待
 
 local skynet = require "skynet"
 local queue = require "skynet.queue"
@@ -38,6 +46,8 @@ local function wakeup(waits)
     end
 end
 
+---#desc 新建队列对象
+---@return table
 function M:new()
     local t = {
         unique_queue = queue(),
@@ -56,6 +66,11 @@ function M:new()
     return t
 end
 
+---#desc 调用并发执行
+---@param key any 不同key可以并发，相同key串行
+---@param func function 调用函数
+---@param ... any 函数参数
+---@return ... 函数返回值
 function M:multi(key, func, ...)
     local co = coroutine.running()
     assert(not self.doing_co[co], "can`t loop call")   --不能嵌套调用
@@ -97,6 +112,10 @@ function M:multi(key, func, ...)
     end
 end
 
+---#desc 调用单发执行，执行单发时，并发都暂时等待
+---@param func function 调用函数
+---@param ... any 函数参数
+---@return ... 函数返回值
 function M:unique(func, ...)
     -- 直接锁住
     self.is_lock = true