Merge pull request #883 from Gowa2017/master

add skynet sc and mongo desc

Author: sumneko

meta/3rd/skynet/library/skynet/db/mongo.lua

@@ -57,7 +57,8 @@ end
 function mongo_db:auth(user, pass)
 
 end
----执行命令
+---执行命令，命令的格式需要参考  [https://docs.mongodb.com/manual/reference/command/](https://docs.mongodb.com/manual/reference/command/),
+---命令的键要单独分开来放，如 mongo_db:runCommand('find','account','limit','1')
 function mongo_db:runCommand(cmd, cmd_v, ...)
 end
 ---获取集合
@@ -78,8 +79,8 @@ end
 ---向集合安全的插入数据
 ---@param doc table
 ---@return boolean ok #是否成功
----@return string err #错误消息
----@return table r #错误返回数据
+---@return string|nil err #错误消息
+---@return table r #成功时表示返回的数据，失败时表示错误的详细信息
 function mongo_collection:safe_insert(doc)
 end
 
@@ -91,8 +92,8 @@ end
 ---安全插入批量数据
 ---@param docs table[]
 ---@return boolean ok #是否成功
----@return string err #错误消息
----@return table r #错误返回数据
+---@return string|nil err #错误消息
+---@return table r #成功时表示返回的数据，失败时表示错误的详细信息
 function mongo_collection:safe_batch_insert(docs)
 
 end
@@ -107,11 +108,11 @@ end
 ---安全更新数据
 ---@param selector table
 ---@param update table
----@param upsert boolean
----@param multi boolean
+---@param upsert boolean #没有数据是否插入
+---@param multi boolean #是否更新多行
 ---@return boolean ok #是否成功
----@return string err #错误消息
----@return table r #错误返回数据
+---@return string|nil err #错误消息
+---@return table r #成功时表示返回的数据，失败时表示错误的详细信息
 function mongo_collection:safe_update(selector, update, upsert, multi)
 
 end
@@ -131,6 +132,7 @@ end
 function mongo_collection:safe_delete(selector, single)
 
 end
+---查找数据，返回的是一个游标，我们需要遍历游标才能获取所有返回
 ---@param query table
 ---@param selector table
 ---@return mongo_cursor
@@ -149,7 +151,7 @@ end
 ---* or collection:createIndex { "key1", "key2",  unique = true }
 ---* or collection:createIndex( { key1 = 1} , { unique = true } )	-- For compatibility
 ---@param arg1 table
----@param arg2 table
+---@param arg2? table
 function mongo_collection:createIndex(arg1, arg2)
 
 end

meta/3rd/skynet/library/skynet/db/mysql.lua

@@ -25,7 +25,7 @@ end
 local STMT = {}
 ---@param sql string
 ---@return boolean #whether ok
----@return STMT # error description table or rows list
+---@return STMT|table # error description table or STMT
 function _M:prepare(sql)
 end
 

meta/3rd/skynet/library/skynet/db/redis.lua

@@ -9,36 +9,55 @@ local redis   = {}
 ---@field db integer
 ---@field username? string
 
----其他指令还可以动态生成
----更多命令查看 https://www.redis.com.cn/commands.html
+---一个 Redis 连接，返回这个 Command 对象。当在此对象上执行指令时，若指令不存在，会在第一次执行的时候构造
+---指令对象的方法。
+---指令的参数的第一个可以是 nil, 也可以是 table，还可以有多个参数。
+---异步形式，底层用 socketchannel 进行通信，这点要注意。
+---更多命令查看 [https://www.redis.com.cn/commands.html](https://www.redis.com.cn/commands.html)
+---@see socketchannel
+---@class command
 local command = {}
-function command:disconnect() end
-function command:exists(k) end
-function command:sismember(key, value) end
-function command:pipeline(ops, resp) end
+function command:disconnect()
+end
+function command:exists(k)
+end
+function command:sismember(key, value)
+end
+function command:pipeline(ops, resp)
+end
 
 --- watch mode, only can  do  SUBSCRIBE, PSUBSCRIBE, UNSUBSCRIBE, PUNSUBSCRIBE, PING  and QUIT command.
+--- we can call watch:message in endless loop.
+---@class watch
 local watch   = {}
-function watch:disconnect() end
+function watch:disconnect()
+end
 ---阻塞模式读取消息
-function watch:message() end
+function watch:message()
+end
 ---subscribe channel
-function watch:subscribe(...) end
+function watch:subscribe(...)
+end
 ---pattern subscribe channels
-function watch:psubscribe(...) end
+function watch:psubscribe(...)
+end
 ---unsubscribe
-function watch:unsubscribe(...) end
+function watch:unsubscribe(...)
+end
 ---punsubscribe
-function watch:punsubscribe(...) end
+function watch:punsubscribe(...)
+end
 
 ---connect to redis server
 ---@param conf redisconfig
 ---@return command
-function redis.connect(conf) end
+function redis.connect(conf)
+end
 
 ---connect to redis server on watch mode
 ---@param conf redisconfig
 ---@return watch
-function redis.watch(conf) end
+function redis.watch(conf)
+end
 
 return redis

meta/3rd/skynet/library/skynet/socketchannel.lua

@@ -2,12 +2,6 @@
 ---socket channel 在创建时，并不会立即建立连接。如果你什么都不做，那么连接建立会推迟到第一次 request 请求时。这种被动建立连接的过程会不断的尝试，即使第一次没有连接上，也会重试。
 ---@class socketchannel
 local socket_channel = {}
-socket_channel.error = setmetatable(
-                           {}, {
-        __tostring = function()
-            return "[Error: socket]"
-        end,
-    })
 
 ---创建一个新的套接字频道
 ---返回结构：
@@ -30,6 +24,7 @@ socket_channel.error = setmetatable(
 ---*     __overload = false,
 ---* }
 ---@param desc table {host, port, backup, auth, response, nodelay, overload}
+---@return socketchannel
 function socket_channel.channel(desc)
 
 end
@@ -39,15 +34,23 @@ end
 function socket_channel:connect(once)
 
 end
+
+---返回值 true 表示协议解析成功，如果为 false 表示协议出错，这会导致连接断开且让 request 的调用者也获得一个 error
+---在 response 函数内的任何异常以及 sock:read 或 sock:readline 读取出错，都会以 error 的形式抛给 request 的调用者。
+---@alias ResponseFunction fun(sock:table): boolean, string
+
 ---发送请求
----@param request string
----@param response? fun(sock:table): boolean, string
+---@param request string binary 请求内容，若不填写 resonse，那么只发送而不接收
+---@param response? ResponseFunction 返回值 true 表示协议解析成功，如果为 false 表示协议出错，这会导致连接断开且让 request 的调用者也获得一个 error
 ---@param padding? table
----@return string
+---@return string # 是由 response 函数返回的回应包的内容（可以是任意类型）
 function socket_channel:request(request, response, padding)
 end
 
-function socket_channel:response(response)
+---用来单向接收一个包。
+---`local resp = channel:response(dispatch)` 与 `local resp = channel:request(req, dispatch)` 等价
+---@param dispatch any
+function socket_channel:response(dispatch)
 end
 ---关闭频道
 function socket_channel:close()