fix: std functions should match official manuals

crates/emmylua_code_analysis/resources/std/coroutine.lua

@@ -32,7 +32,7 @@ function coroutine.create(f) end
 ---@param co? thread
 ---@return boolean
 ---@nodiscard
-function coroutine.isyieldable() end
+function coroutine.isyieldable(co) end
 
 ---@version > 5.4
 ---
@@ -61,10 +61,18 @@ function coroutine.close(co) end
 ---@return any ...
 function coroutine.resume(co, val1, ...) end
 
+---@version 5.1
+---
+--- Returns the running coroutine, or nil when called by the main thread.
+---@return thread?
+---@nodiscard
+function coroutine.running() end
+
+---@version > 5.2
 ---
 --- Returns the running coroutine plus a boolean, true when the running
 --- coroutine is the main one.
----@return thread, string
+---@return thread, boolean
 ---@nodiscard
 function coroutine.running() end
 

crates/emmylua_code_analysis/resources/std/debug.lua

@@ -40,9 +40,11 @@ function debug.getfenv(o) end
 --- Returns the current hook settings of the thread, as three values: the
 --- current hook function, the current hook mask, and the current hook count
 --- (as set by the `debug.sethook` function).
----@overload fun():thread
+---@overload fun():function?, string, integer
 ---@param thread thread
----@return thread
+---@return function? hook
+---@return string mask
+---@return integer count
 function debug.gethook(thread) end
 
 ---@class debuglib.DebugInfo
@@ -65,7 +67,7 @@ function debug.gethook(thread) end
 
 ---@alias debuglib.InfoWhat
 ---|+"n"     # `name`, `namewhat`
----|+"S"     # `source`, `short_src`, `linedefined`, `lalinedefined`, `what`
+---|+"S"     # `source`, `short_src`, `linedefined`, `lastlinedefined`, `what`
 ---|+"l"     # `currentline`
 ---|+"t"     # `istailcall`
 ---|+"u"     # `nups`, `nparams`, `isvararg`
@@ -177,8 +179,8 @@ function debug.getregistry() end
 --- no known names (variables from chunks saved without debug information).
 ---@param f function
 ---@param up integer
----@return string name
----@return any    value
+---@return string? name
+---@return any?    value
 ---@nodiscard
 function debug.getupvalue(f, up) end
 
@@ -254,12 +256,12 @@ function debug.sethook(thread, hook, mask, count) end
 --- raises an error when called with a `level` out of range. (You can call
 --- `getinfo` to check whether the level is valid.) Otherwise, it returns the
 --- name of the local variable.
----@overload fun(level:integer, var:string, value:any):string
+---@overload fun(level:integer, var:string, value:any):string?
 ---@param thread thread
 ---@param level integer
 ---@param var string
 ---@param value any
----@return string
+---@return string?
 function debug.setlocal(thread, level, var, value) end
 
 ---
@@ -279,7 +281,7 @@ function debug.setmetatable(value, meta) end
 ---@param f fun():any
 ---@param up integer
 ---@param value any
----@return string
+---@return string?
 function debug.setupvalue(f, up, value) end
 
 --- Sets the given `value` as the `n`-th associated to the given `udata`.
@@ -289,22 +291,40 @@ function debug.setupvalue(f, up, value) end
 ---@param udata userdata
 ---@param value any
 ---@param n integer
----@return userdata
+---@return userdata?
 function debug.setuservalue(udata, value, n) end
 
---- Generates a traceback of the call stack.
---- When called with no arguments, returns a traceback of the current thread.
---- When the first argument is a thread, the traceback is generated for that thread;
---- the optional second argument (if a string) is prepended to the traceback, and the
---- optional third argument sets the level where the traceback should start (default is 1).
---- When the first argument is not a thread and not nil, it is treated as an optional message.
---- In that case, the traceback is generated for the current thread and the second argument,
---- if provided, specifies the starting level.
+---@version 5.1, JIT
+---
+--- Returns a string with a traceback of the call stack. An optional message
+--- string is appended at the beginning of the traceback. An optional level
+--- number tells at which level to start the traceback (default is 1, the
+--- function calling traceback).
+---@overload fun(): string
+---@overload fun(message?: string, level?: integer): string
+---@param thread? thread
+---@param message? string
+---@param level? integer
+---@return string
+function debug.traceback(thread, message, level) end
+
+---@version > 5.2
+---
+--- If message is present but is neither a string nor nil, this function
+--- returns message without further processing. Otherwise, it returns a string
+--- with a traceback of the call stack. The optional message string is appended
+--- at the beginning of the traceback. An optional level number tells at which
+--- level to start the traceback (default is 1, the function calling traceback).
+---@generic T
 ---@overload fun(): string
 ---@overload fun(message?: string, level?: integer): string
----@param thread? thread|integer  Optional thread or nil. If not a thread, it is interpreted as the message.
----@param message? string Optional message to prepend to the traceback. If not a string (or nil), it is returned as is.
----@param level? integer  Optional level from which to start the traceback (default is 1).
+---@overload fun(message: T, level?: integer): T
+---@overload fun(thread: thread): string
+---@overload fun(thread: thread, message?: string, level?: integer): string
+---@overload fun(thread: thread, message: T, level?: integer): T
+---@param thread? thread
+---@param message? string|T
+---@param level? integer
 ---@return string
 function debug.traceback(thread, message, level) end
 

crates/emmylua_code_analysis/resources/std/global.lua

@@ -84,7 +84,7 @@ function collectgarbage(opt, ...) end
 --- `dofile` propagates the error to its caller (that is, `dofile` does not run
 --- in protected mode).
 ---@param filename? string
----@return table
+---@return any ...
 function dofile(filename) end
 
 ---
@@ -299,6 +299,7 @@ function rawlen(v) end
 ---@param table table
 ---@param index any
 ---@param value any
+---@return table
 function rawset(table, index, value) end
 
 ---
@@ -469,8 +470,15 @@ function unpack(list, i, j) end
 
 ---@version > 5.4
 ---
----@param message string
-function warn(message) end
+--- Emits a warning with a message composed by the concatenation of all its arguments (which should be strings).
+---
+--- By convention, a one-piece message starting with '@' is intended to be a control message,
+--- which is a message to the warning system itself. In particular,
+--- the standard warning function in Lua recognizes the control messages "@off", to stop the emission of warnings,
+--- and "@on", to (re)start the emission; it ignores unknown control messages.
+---@param msg1 string|number
+---@param ... string|number
+function warn(msg1, ...) end
 
 ---@type string[]
 arg = {}

crates/emmylua_code_analysis/resources/std/math.lua

@@ -17,7 +17,7 @@
 math = {}
 
 ---
---- Returns the absolute value of `x`. (integer/float)
+--- Returns the maximum value between `x` and `-x`. (integer/float)
 ---@overload fun(x:integer):integer
 ---@param x number
 ---@return number
@@ -160,12 +160,30 @@ function math.rad(x) end
 ---@return integer
 function math.random(m, n) end
 
+---@version 5.1, 5.2, 5.3
 ---
 --- Sets `x` as the "seed" for the pseudo-random generator: equal seeds
 --- produce equal sequences of numbers.
 ---@param x integer
 function math.randomseed(x) end
 
+---@version > 5.3
+---
+--- When called with at least one argument, the integer parameters `x` and `y`
+--- are joined into a 128-bit seed that is used to reinitialize the pseudo-random
+--- generator; equal seeds produce equal sequences of numbers. The default for
+--- `y` is zero.
+---
+--- When called with no arguments, Lua generates a seed with a weak attempt
+--- for randomness.
+---
+--- This function returns the two seed components that were effectively used,
+--- so that setting them again repeats the sequence.
+---@param x? integer
+---@param y? integer
+---@return integer, integer
+function math.randomseed(x, y) end
+
 ---
 --- Returns the sine of `x` (assumed to be in radians).
 ---@param x number
@@ -198,7 +216,7 @@ function math.tointeger(x) end
 --- Returns "`integer`" if `x` is an integer, "`float`" if it is a float, or
 --- **nil** if `x` is not a number.
 ---@param x any
----@return 'integer'|'float'|'nil'
+---@return 'integer'|'float'|nil
 function math.type(x) end
 
 ---@version >5.3

crates/emmylua_code_analysis/resources/std/os.lua

@@ -132,17 +132,15 @@ function os.execute(command) end
 ---
 --- If the optional second argument `close` is true, closes the Lua state before
 --- exiting.
----@param code integer
+---@param code? boolean|integer
 ---@param close? boolean
----@return integer
 function os.exit(code, close) end
 
 ---@version 5.1
 ---
 --- Calls the C function exit, with an optional `code`, to terminate the host
 --- program. The default value for `code` is the success code.
----@param code integer
----@return integer
+---@param code? integer
 function os.exit(code) end
 
 ---

crates/emmylua_code_analysis/resources/std/string.lua

@@ -147,6 +147,13 @@ function string.format(fmt, ...) end
 ---@return fun():string?...
 function string.gmatch(s, pattern) end
 
+---@version > 5.4
+---@param s string
+---@param pattern string
+---@param init? integer
+---@return fun():string?...
+function string.gmatch(s, pattern, init) end
+
 ---
 --- Returns a copy of `s` in which all (or the first `n`, if given)
 --- occurrences of the `pattern` have been replaced by a replacement string
@@ -230,9 +237,9 @@ function string.match(s, pattern, init) end
 --- Returns a binary string containing the values `v1`, `v2`, etc. packed (that
 --- is, serialized in binary form) according to the format string `fmt`.
 ---@param fmt string
----@param v1 string
----@param v2? string
----@param ... string
+---@param v1 string|number|integer
+---@param v2? string|number|integer
+---@param ... string|number|integer
 ---@return string
 function string.pack(fmt, v1, v2, ...) end
 

crates/emmylua_code_analysis/resources/std/table.lua

@@ -34,11 +34,10 @@ function table.concat(list, sep, i, j) end
 --- elements to `list[pos]`, `list[pos+1]`, `···`, `list[#list]`. The default
 --- value for `pos` is ``#list+1`, so that a call `table.insert(t,x)`` inserts
 --- `x` at the end of list `t`.
----@overload fun(list:table, value:any):integer
+---@overload fun(list:table, value:any)
 ---@param list table
 ---@param pos integer
 ---@param value any
----@return integer
 function table.insert(list, pos, value) end
 
 ---@version > 5.3
@@ -100,7 +99,6 @@ function table.remove(list, pos) end
 ---@generic V
 ---@param list V[]
 ---@param comp? fun(a:V, b:V):boolean
----@return integer
 function table.sort(list, comp) end
 
 ---@version > 5.2, JIT

crates/emmylua_code_analysis/resources/std/utf8.lua

@@ -40,9 +40,15 @@ utf8.charpattern = ""
 --- (in bytes) and `c` the code point of each character. It raises an error if
 --- it meets any invalid byte sequence.
 ---@param s string
----@return string
+---@return fun(s: string, i?: integer): integer, integer
 function utf8.codes(s) end
 
+---@version > 5.4
+---@param s string
+---@param lax? boolean
+---@return fun(s: string, i?: integer): integer, integer
+function utf8.codes(s, lax) end
+
 ---
 --- Returns the codepoints (as integers) from all characters in `s` that start
 --- between byte position `i` and `j` (both included). The default for `i` is
@@ -55,6 +61,15 @@ function utf8.codes(s) end
 ---@return integer
 function utf8.codepoint(s, i, j) end
 
+---@version > 5.4
+---@overload fun(s:string):integer
+---@param s string
+---@param i? integer
+---@param j? integer
+---@param lax? boolean
+---@return integer
+function utf8.codepoint(s, i, j, lax) end
+
 ---
 --- Returns the number of UTF-8 characters in string `s` that start between
 --- positions `i` and `j` (both inclusive). The default for `i` is 1 and for
@@ -63,6 +78,15 @@ function utf8.codepoint(s, i, j) end
 ---@param s    string
 ---@param i?   integer
 ---@param j?   integer
+---@return integer?
+---@return integer? errpos
+---@nodiscard
+function utf8.len(s, i, j) end
+
+---@version > 5.4
+---@param s    string
+---@param i?   integer
+---@param j?   integer
 ---@param lax? boolean
 ---@return integer?
 ---@return integer? errpos