Merge pull request #1691 from Gowa2017/master

add some optional parameters

Author: sumneko

meta/3rd/luaecs/library/ecs.lua

@@ -79,7 +79,7 @@ end
 function meta:select(pat)
 end
 
----Sync all then component of the eneity represent by a iter
+---Sync all then component of the entity represent by a iter to LUA
 ---@param iter number|ITER #ITER or entity id
 ---@return table
 ---@see ECSWorld#_read
@@ -107,7 +107,7 @@ function meta:dumpid(name)
 end
 
 ---Update world, will free removed(default, or with tag `tagname`) entity.
----@param tagname? string #tagname
+---@param tagname? string #tagname, default is REMOVED, but we also can use other tag to delete entities.
 ---@see ECSWorld#_update
 function meta:update(tagname)
 end
@@ -132,6 +132,7 @@ local M = {
 }
 
 ---Lua function
+---Construct a new LuaECS World
 ---@return ECSWorld
 function M.world()
 end
@@ -156,11 +157,11 @@ end
 function meta:template_instance(eid, temp, obj)
 end
 
----Get an entity's component.
+---Get an entity's one component, can can write the value.
 ---@param eid integer
 ---@param pat string #only one key
----@param value any # when with this values, is write.
----@return any # pattern key is tag, return boolean; lua type, return lua data; else table.
+---@param value? any # when with this values, is write.
+---@return any|nil # pattern key is tag, return boolean; lua type, return lua data; else table; if write, return nil.
 ---@see ECSWorld#readall
 ---@see ECSWorld#fetch
 function meta:access(eid, pat, value)
@@ -172,7 +173,7 @@ end
 function meta:count(pat)
 end
 
----Extend an iter with patther.
+---Extend an iter with pattern.
 ---@param iter ITER
 ---@param expat string
 ---@see ECSWorld#_read
@@ -183,10 +184,11 @@ function meta:extend(iter, expat) end
 ---@return integer #component id
 function meta:component_id(name) end
 
----Persist User
+---Persist Use
 function meta:read_component(reader, name, offset, stride, n) end
 
 ---Get the first entity of pattern `pattern`
+---We can use this as a signletone component.
 ---@param pattern string
 ---@return ITER
 function meta:first(pattern) end
@@ -220,6 +222,7 @@ function meta:type(name) end
 function meta:filter(tagname, pat) end
 
 ---Fetch entity's component with pattern `pat`
+---You can use out, update and then w:sumit() to modify entity.
 ---@param eid integer
 ---@param pat? string
 ---@see ECSWorld#readall
@@ -355,7 +358,9 @@ function meta:_access(...) end
 function meta:__gc(...) end
 
 ---C API
--- Add entity (eid) into a group with groupid (32bit integer)
+--- Add entity (eid) into a group with groupid (32bit integer)
+---**NOTE:We can add entity to a group, but we can not remove it from a group.**
+---**NOTE:We can iterate a group, but we can not random visit a group member.**
 ---@param groupid number #32bit
 ---@param eid number
 function meta:group_add(groupid, eid) end

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

@@ -205,7 +205,7 @@ end
 ---@param addr SERVICEADDR @目标服务地址
 ---@param typename string @类型名
 ---@param msg lightuserdata
----@param sz number
+---@param sz? number
 function skynet.rawsend(addr, typename, msg, sz)
 end
 
@@ -217,6 +217,7 @@ end
 ---@param addr SERVICEADDR @目标服务地址
 ---@param typename string @类型名
 ---@vararg any @传输的数据
+---@return ...
 function skynet.call(addr, typename, ...)
 end
 
@@ -296,7 +297,7 @@ end
 --- 用于启动一个新的 Lua 服务。name 是脚本的名字（不用写 .lua 后缀）。只有被启动的脚本的 start 函数返回后，这个 API 才会返回启动的服务的地址，这是一个阻塞 API 。如果被启动的脚本在初始化环节抛出异常，或在初始化完成前就调用 skynet.exit 退出，skynet.newservice 都会抛出异常。如果被启动的脚本的 start 函数是一个永不结束的循环，那么 newservice 也会被永远阻塞住。
 --- > 启动参数其实是以字符串拼接的方式传递过去的。所以不要在参数中传递复杂的 Lua 对象。接收到的参数都是字符串，且字符串中不可以有空格（否则会被分割成多个参数）。这种参数传递方式是历史遗留下来的，有很多潜在的问题。目前推荐的惯例是，让你的服务响应一个启动消息。在 newservice 之后，立刻调用 skynet.call 发送启动请求。
 ---@param name string #脚本名字
----@vararg string #可选参数
+---@vararg string|number #可选参数
 function skynet.newservice(name, ...)
 end
 

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

@@ -204,7 +204,7 @@ end
 function mongo_cursor:limit(amount)
 end
 ---统计行数
----@param with_limit_and_skip boolean
+---@param with_limit_and_skip? boolean
 function mongo_cursor:count(with_limit_and_skip)
 end
 ---是否有下一行

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

@@ -1,5 +1,5 @@
 ---@meta
-local redis   = {}
+local redis = {}
 
 ---@class redisconfig
 ---@field host string
@@ -19,31 +19,50 @@ local redis   = {}
 local command = {}
 function command:disconnect()
 end
+
+---Is key exists
+---@param k string
+---@return boolean
 function command:exists(k)
 end
+
+---Does value is a member of set key.
+---@param key string #key of a set
+---@param value string #value
 function command:sismember(key, value)
 end
+
+---Pipline command
+---If resp is a table and exits, return boolean, resp.
+---Or return the last result. boolean, out
+---@param ops string[]
+---@param resp? table
 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   = {}
+local watch = {}
 function watch:disconnect()
 end
+
 ---阻塞模式读取消息
 function watch:message()
 end
+
 ---subscribe channel
 function watch:subscribe(...)
 end
+
 ---pattern subscribe channels
 function watch:psubscribe(...)
 end
+
 ---unsubscribe
 function watch:unsubscribe(...)
 end
+
 ---punsubscribe
 function watch:punsubscribe(...)
 end

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

@@ -11,52 +11,62 @@ local socket = {}
 ---@return number @skynet对套接字描述符的表示
 function socket.open(addr, port)
 end
+
 ---* 绑定系统文件描述符
 ---@param os_fd  number
 ---@return number @skynet对套接字描述符的表示
 function socket.bind(os_fd)
 end
+
 ---* 等价于 socket.bind(0)，绑定到标准输出
 ---@return number @skynet对套接字描述符的表示
 function socket.stdin()
 end
+
 ---* accept 是一个函数。每当一个监听的 id 对应的 socket 上有连接接入的时候，都会调用 accept 函数。这个函数会得到接入连接的 id 以及 ip 地址。你可以做后续操作。
 ---* 开始收发套接字数据，并设置一个回调
 ---* 这个函数会将套接字索引与一个 Lua 的结构封装起来，并在协程内挂起 (skynet.wait)
 ---* 当有数据事件到达时，就会 skynet.wakeup 协程来
 ---@param id number @skynet套接字索引
----@param accept fun(...) @事件回调函数
+---@param accept? fun(...) @事件回调函数，监听字才需要这个
 ---@return number | nil, error
 function socket.start(id, accept)
 end
+
 ---* 暂停收发一个套接字上的数据
 ---@param id number @skynet套接字索引
 function socket.pause(id)
 end
+
 ---* 强行关闭一个连接。和 close 不同的是，它不会等待可能存在的其它 coroutine 的读操作。
 ---* 一般不建议使用这个 API ，但如果你需要在 __gc 元方法中关闭连接的话，shutdown 是一个比 close 更好的选择（因为在 gc 过程中无法切换 coroutine）
 ---@param id number @skynet套接字索引
 function socket.shutdown(id)
 end
+
 ---* 在极其罕见的情况下，需要粗暴的直接关闭某个连接，而避免 socket.close 的阻塞等待流程，可以使用它。
 ---@param id number @skynet套接字索引
 function socket.close_fd(id)
 end
+
 ---* 关闭一个连接，这个 API 有可能阻塞住执行流。因为如果有其它 coroutine 正在阻塞读这个 id 对应的连接，会先驱使读操作结束，close 操作才返回。
 ---@param id number @skynet套接字索引
 function socket.close(id)
 end
+
 ---从一个 socket 上读 sz 指定的字节数。如果读到了指定长度的字符串，它把这个字符串返回。如果连接断开导致字节数不够，将返回一个 false 加上读到的字符串。如果 sz 为 nil ，则返回尽可能多的字节数，但至少读一个字节（若无新数据，会阻塞）。
 ---@param id number @skynet套接字索引
 ---@param sz number | nil @要读取的字节数,nil 尽可能多的读
 ---@return string | nil, string
 function socket.read(id, sz)
 end
+
 ---* 从一个 socket 上读所有的数据，直到 socket 主动断开，或在其它 coroutine 用 socket.close 关闭它。
 ---@param id number @skynet套接字索引
 ---@return buffer | nil, buffer
 function socket.readall(id)
 end
+
 ---* 从一个 socket 上读一行数据。sep 指行分割符。默认的 sep 为 "\n"。读到的字符串是不包含这个分割符的。
 ---@param id number @skynet套接字索引
 ---@return buffer | nil, buffer
@@ -67,11 +77,13 @@ end
 ---@param id number @skynet套接字索引
 function socket.block(id)
 end
+
 ---* 是否合法套接字
 ---@param id number @skynet套接字索引
 ---@return boolean
 function socket.invalid(id)
 end
+
 ---* 是否已断开
 ---@param id number @skynet套接字索引
 ---@return boolean
@@ -80,40 +92,49 @@ end
 
 ---* 监听一个端口，返回一个 id ，供 start 使用。
 ---@param host string @地址，可以是 ip:port
----@param port number @断开，可为 nil，此时从 host 内获取端口信息
----@param backlog number @队列长度
+---@param port? number @端口，可为 nil，此时从 host 内获取端口信息
+---@param backlog? number @队列长度
 ---@return number @skynet套接字索引
 function socket.listen(host, port, backlog)
 end
+
 ---* 清除 socket id 在本服务内的数据结构，但并不关闭这个 socket 。这可以用于你把 id 发送给其它服务，以转交 socket 的控制权。
 function socket.abandon(id)
 end
+
 ---* 设置缓冲区大小
 ---@param id number @skynet套接字索引
 ---@param limit number @缓冲区大小
 function socket.limit(id, limit)
 end
+
 function socket.udp(callback, host, port)
 end
+
 function socket.udp_connect(id, addr, port, callback)
 end
+
 function socket.warning(id, callback)
 end
+
 function socket.onclose(id, callback)
 end
+
 ---* 把一个字符串置入正常的写队列，skynet 框架会在 socket 可写时发送它。
 ---* 这和 socketdriver.send 是一个
 ---@see socketdriver#send
 ---@param id number @skynet套接字索引
 ---@param msg string @数据
----@param sz number @大小
+---@param sz? number @大小，如果是字符串则不需要
 function socket.write(id, msg, sz)
 end
+
 ---* 把字符串写入低优先级队列。如果正常的写队列还有写操作未完成时，低优先级队列上的数据永远不会被发出。只有在正常写队列为空时，才会处理低优先级队列。但是，每次写的字符串都可以看成原子操作。不会只发送一半，然后转去发送正常写队列的数据。
 ---@param id number @skynet套接字索引
 ---@param msg string @数据
 function socket.lwrite()
 end
+
 function socket.header()
 end