fix: std functions should match official manuals

[EfveZombie]

Summary of Changes

This PR systematically audits and corrects the EmmyLua type-annotation stubs under crates/emmylua_code_analysis/resources/std/ so that parameter types, return types, version guards, and doc-comments accurately reflect the official Lua manuals (5.1 through 5.4).

---

File-by-File Breakdown

1. coroutine.lua (+12 / −2)

Item	Change	Rationale
coroutine.isyieldable(co)	Added the co parameter name to the function signature	Lua 5.4 manual specifies an optional co argument
coroutine.running() (5.1)	New overload — returns thread? only	In Lua 5.1, coroutine.running() returns nil when called from the main thread (no boolean)
coroutine.running() (≥5.2)	Fixed return type from thread, string → thread, boolean	The second return value is a boolean, not a string

2. debug.lua (+42 / −18)

Item	Change	Rationale
debug.gethook()	Return type corrected from thread → function?, string, integer; overload updated similarly	The function returns the hook function, mask string, and count — not a thread
debuglib.InfoWhat alias	Fixed typo: lalinedefined → lastlinedefined	Typo fix
debug.getupvalue()	Return types changed to string? and any? (nilable)	Returns nil when the index is out of range
debug.setlocal()	Return type changed to string?	Returns nil on invalid level
debug.setupvalue()	Return type changed to string?	Returns nil when index is out of range
debug.setuservalue()	Return type changed to userdata?	Can return nil per the manual
debug.traceback()	Split into 5.1 and ≥5.2 versions with distinct overloads; ≥5.2 version adds generic T passthrough for non-string messages	In Lua ≥5.2, if message is neither a string nor nil, it is returned as-is (identity passthrough). The previous annotation did not model this

3. global.lua (+3 / −2)

Item	Change	Rationale
dofile()	Return type changed from table → any ...	dofile returns all values returned by the chunk, not necessarily a table
rawset()	Added @return table	rawset returns the table being modified
warn()	Parameter renamed message → msg1, ...; accepts variadic strings	Lua 5.4 warn accepts multiple string fragments concatenated together

4. math.lua (+20 / −2)

Item	Change	Rationale
math.abs()	Doc-comment updated: "absolute value" → "maximum value between x and -x"	Matches the exact wording in the Lua 5.4 manual
math.randomseed() (5.1–5.3)	Added @version 5.1, 5.2, 5.3 guard	Restricts the single-arg form to the correct versions
math.randomseed() (≥5.4)	New overload — accepts optional x, y and returns integer, integer	Lua 5.4 changed randomseed to accept two optional seed components and return them
math.type()	Return type fixed from 'integer'|'float'|'nil' → 'integer'|'float'|nil	'nil' (string literal) is incorrect; the function returns actual nil

5. os.lua (+2 / −4)

Item	Change	Rationale
os.exit() (≥5.2)	code parameter type changed to boolean|integer, made optional; removed erroneous @return integer	os.exit does not return; code can be a boolean (true/false) in Lua ≥5.2
os.exit() (5.1)	code made optional; removed @return integer	Same — os.exit never returns

6. string.lua (+8 / −5)

Item	Change	Rationale
string.gmatch() (≥5.4)	New overload with optional init parameter	Lua 5.4 added an init position argument
string.pack()	Parameter types widened from string → string|number|integer	string.pack packs numbers and integers, not just strings

7. table.lua (+1 / −3)

Item	Change	Rationale
table.insert()	Removed @return integer from both the overload and the main signature	table.insert returns nothing
table.sort()	Removed @return integer	table.sort returns nothing (sorts in-place)

8. utf8.lua (+24 / −2)

Item	Change	Rationale
utf8.codes()	Return type corrected from string → fun(s: string, i?: integer): integer, integer (iterator)	utf8.codes returns an iterator function, not a string
utf8.codes() (≥5.4)	New overload with lax parameter	Lua 5.4 added a lax boolean flag
utf8.codepoint() (≥5.4)	New overload with lax parameter	Same as above
utf8.len()	Split into base (≤5.3) and ≥5.4 versions; ≥5.4 adds lax parameter	Lua 5.4 added the lax flag

---

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the accuracy of EmmyLua type annotations for the Lua standard library. By meticulously comparing existing stubs against official Lua manuals from versions 5.1 to 5.4, it ensures that function signatures, parameter types, return values, and version-specific behaviors are correctly represented. This effort improves static analysis capabilities and provides more reliable type hints for developers working with Lua.

Highlights

• Type Annotation Alignment: Systematically audited and corrected EmmyLua type-annotation stubs to accurately reflect official Lua manuals across versions 5.1 through 5.4.
• Parameter and Return Type Corrections: Adjusted parameter and return types for numerous standard library functions to match documented behavior, including making types nilable where appropriate.
• Version-Specific Overloads and Guards: Introduced new function overloads and version guards to correctly model functions that behave differently across various Lua versions (e.g., coroutine.running, math.randomseed, debug.traceback, string.gmatch, utf8 functions).
• Doc-Comment and Typo Updates: Updated doc-comments for improved clarity and fixed a typo in the debuglib.InfoWhat alias.
• Removed Erroneous Return Types: Removed incorrect @return integer annotations from functions like os.exit, table.insert, and table.sort which do not return a value.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• crates/emmylua_code_analysis/resources/std/coroutine.lua
  • Added the co parameter name to coroutine.isyieldable(co).
  • Introduced a new overload for coroutine.running() for Lua 5.1, returning thread? only.
  • Fixed the return type for coroutine.running() (≥5.2) from thread, string to thread, boolean.
• crates/emmylua_code_analysis/resources/std/debug.lua
  • Corrected debug.gethook() return type from thread to function?, string, integer and updated its overload.
  • Fixed typo in debuglib.InfoWhat alias: lalinedefined changed to lastlinedefined.
  • Changed return types for debug.getupvalue() to string? and any? (nilable).
  • Changed return type for debug.setlocal() to string?.
  • Changed return type for debug.setupvalue() to string?.
  • Changed return type for debug.setuservalue() to userdata?.
  • Split debug.traceback() into distinct 5.1 and ≥5.2 versions, with the ≥5.2 version adding generic T passthrough for non-string messages.
• crates/emmylua_code_analysis/resources/std/global.lua
  • Changed dofile() return type from table to any ....
  • Added @return table annotation to rawset().
  • Renamed warn() parameter from message to msg1, ... and updated it to accept variadic strings.
• crates/emmylua_code_analysis/resources/std/math.lua
  • Updated math.abs() doc-comment to reflect the exact wording from the Lua 5.4 manual.
  • Added @version 5.1, 5.2, 5.3 guard to math.randomseed() (single-arg form).
  • Introduced a new overload for math.randomseed() (≥5.4) that accepts optional x, y and returns integer, integer.
  • Fixed math.type() return type from 'integer'|'float'|'nil' to 'integer'|'float'|nil.
• crates/emmylua_code_analysis/resources/std/os.lua
  • Changed os.exit() (≥5.2) code parameter type to boolean|integer, made it optional, and removed erroneous @return integer.
  • Made os.exit() (5.1) code optional and removed erroneous @return integer.
• crates/emmylua_code_analysis/resources/std/string.lua
  • Added a new overload for string.gmatch() (≥5.4) with an optional init parameter.
  • Widened string.pack() parameter types from string to string|number|integer.
• crates/emmylua_code_analysis/resources/std/table.lua
  • Removed @return integer from table.insert()'s overload and main signature.
  • Removed @return integer from table.sort().
• crates/emmylua_code_analysis/resources/std/utf8.lua
  • Corrected utf8.codes() return type from string to an iterator function.
  • Added a new overload for utf8.codes() (≥5.4) with a lax parameter.
  • Added a new overload for utf8.codepoint() (≥5.4) with a lax parameter.
  • Split utf8.len() into base (≤5.3) and ≥5.4 versions, with the ≥5.4 version adding a lax parameter.

Activity

• No human activity has been recorded for this pull request yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request provides a comprehensive and valuable update to the EmmyLua standard library stubs, aligning them more closely with the official Lua manuals for versions 5.1 through 5.4. The changes are well-researched and systematically applied across multiple modules, correcting parameter types, return types, and version guards. I've found a couple of minor areas for further improvement in debug.lua to enhance consistency with the official documentation, but overall this is an excellent set of fixes.

[gemini-code-assist]

According to the Lua 5.4 reference manual, debug.setuservalue always returns the udata object and does not return nil. The documentation comment on lines 287-290 appears to be incorrect. To align with the official manual, the return type should be userdata.

---@return userdata

[gemini-code-assist]

For consistency with the defined overloads, the main function's return type should be string|T. Several overloads for this function can return a value of the generic type T (e.g., fun(message: T, level?: integer): T), but the main signature only declares string as a return type.

---@return string|T

[CppCXY]

Add JIT

[CppCXY]

warn first param support this:
/// @on - enable warnings (stderr mode)
/// @off - disable warnings
/// @store - store warnings in _WARN global
/// @Normal - restore normal stderr output