Add type annotations to all functions and fields of modutil

[alexmaichen]

Most code-editors provide a type-checker for the most common languages. Static type-checking guarantees the program will never crash from lack of type-safety.
Due to being an interpreted dynamically typed language, Lua's typechecker isn't very good on its own. One can help it by adding special comments before variable or function declarations to tell it what the expected value-type in that spot is. If there is a type mismatch between the expected and the provided, the typechecker will show an error (or in the case of lua's typechecker, a warning)

Documentation about annotations found here https://luals.github.io/wiki/annotations/
The main 3 notations to keep in mind would be:

-- variables
---@type variablename type
-- tables
---@type tablevariablename table<keytype, valuetype>
-- functions (to avoid the rather verbose `---@param name type` and `---@return name type` alternative)
---@type fun(param1: type1, param2: type2, param3: type3, ...): returntype

Unfortunately, I cannot find an example of a mod that uses type hints to justify this by precedent, and the game doesn't either; would be nice to have though.

[alexmaichen]

I also took the liberty to unify the style a bit. The use of whitespace in table-definitions, function-calls, and indexing was inconsistent (sometimes there were spaces between the braces/parentheses/brackets and the elements contained, and sometimes not. I have no problem with adding spaces between stuff, however it is way easier to find-and-replace "( " and " )" by "(" and ")" than figuring out a regex to add spaces to only the places where they are missing, so I went with removing instead of adding).

Modutil has an Array.Slice method based on python's list-slicing, but in python one can also slice strings since they both inherit from the Iterable class, and as such I added a ModUtil.String.Slice method.

main...alexmaichen:ModUtil:main
Ready for PR whenever. Will happily rebase to a new branch if necessary.

[AndreLouisIssa]

thanks for your issue but it's not in line with the structure of this project

• the changelog should not be altered manually, it is controlled by the release workflow, so all unreleased changes should remain under the unreleased section of the changelog
• modutil was made for Hades 1 and Hades 2, which have the style of spaces between brackets (as well as everything being PascalCase), the new Hell2Modding component of modutil uses a different style (closer to typical lua, using snake_case or lowercase, and no spaces between brackets)
• it already has type annotations via the defs.lua files, but the part retrofitted to the original part of modutil is incomplete/WIP

[AndreLouisIssa]

Unfortunately, I cannot find an example of a mod that uses type hints to justify this by precedent, and the game doesn't either; would be nice to have though.

https://github.com/SGG-Modding/ModUtil/blob/main/src/def.lua
https://github.com/LuaENVY/ENVY/blob/main/src/def.lua
https://github.com/erumi321/Hades2UILibrary/blob/main/src/def_auto.lua
https://github.com/excellent-ae/zannc-GodsAPI/blob/main/src/def_auto.lua

(def.lua is annotations for the library itself, def_auto.lua is annotations for what happens to the consumer of the library if they run the library's .auto function)

[AndreLouisIssa]

Basically it's problematic to use type hinting within your own mod's code because the loader, the game's engine, the game's scripts, and our scripts are all too dynamic for it to make any inferences (it uses different lua environments, looped assignments, metatables etc), and the exposed API between them are also opaque to the language server. So the only type hinting we can do is via our own handwritten definition files for the public API facing between mods.

[AndreLouisIssa]

That being said we are attempting to autogenerate some of it

https://github.com/SGG-Modding/Hell2Modding/tree/master/docs/lua/tables/definitions
https://github.com/SGG-Modding/Hades2GameDef
https://github.com/SGG-Modding/LuaDocGen

[AndreLouisIssa]

@alexmaichen the most helpful thing would be to work off this branch
https://github.com/SGG-Modding/ModUtil/tree/improve_defs
and work down the def files, such as https://github.com/SGG-Modding/ModUtil/blob/improve_defs/src/def_mod.lua
moving the commented region downwards as that part is converted to a stub and then given type annotations

note on my style is that I make sure every definition is namespaced because they have global name collisions, also I will put * to represent a 'virtual' definition- that is something that only exists in the lua language server, vs a 'concrete' definition which gets ., such as SGG_Modding-ModUtil-Mod*Proxy (notice the *) vs SGG_Modding-ModUtil-Mod.ToString.Deep (notice the .)

[alexmaichen]

Noted, will do (work off the other branch), and thank you for the information.