Adoption of Teal/EmmyLua typing anotation

[walking-octopus]

Motivation

Any non-trivial Lua code quickly turns into a mess of unexpected behavior, half-broken error handling, and other kinds of runtime errors. A robust typing system can allow the compiler or linter to statically check if the data passes has correct shape, preventing such bugs, helping create more reliable software and waste less time debugging.

Both OpenComputers and its users would greatly benefit from maintaining official typing hints.

Implementation details

The main approaches to static typing in Lua are EddyLua typing hints and Teal.

Teal

A statically typed dialect of Lua that compiles to it, similar to what TypeScript is to JavaScript. Uses declaration files to add typing to imported code, including that which used FFI.

A Teal program must have valid types to compile.

Example:

local record MyCompositeType
   record MyPointType
      x: number
      y: number
   end

   center: MyPointType
    -- insert more stuff here
end

return MyCompositeType

EmmyLua

EmmyLua is an adhoc spec for typing hint comments, first started by the same named JetBrains plugin but later adopted by LuaLS/lua-language-server, becoming the typical way to add basic type linting to Lua code.

Because it functions as a linter, nothing prevents the user from running the invalidly typed code but their IDE will report the issue.

To add typing to some module that lives on the other side of the FFI, you'll need to create a stub, an empty placeholder with the typing hints.

Example:

---@class item
---@field public damage number the current damage value of the item.
---@field public maxDamage number the maximum damage this item can have before it breaks.
---@field public size number the current stack size of the item.
---@field public maxSize number the maximum stack size of this item.
---@field public id number the Minecraft id of the item. Note that this field is only included if insertIdsInConverters=true in the configs, and can vary between servers!
---@field public name string the untranslated item name, which is an internal Minecraft value like oc:item.FloppyDisk
---@field public label string the translated item name
---@field public hasTag boolean whether or not the item has an NBT tag associated with it.
local item={}

Prior works:

• https://github.com/marcin212/oc-docs-idea
• https://github.com/sewbacca/CC-EmmyLua-Docs

End note:

While I understand the maintainers may have quite little time on their hands to dedicate to this project and this may not seem like an important issue, I believe this kind of static analysis is imperative to ensuring proper developer experience. Dynamic typing can be very very frustrating once your program grows from a tiny script you can keep in mind to a mid-size codebase; this simple documentation effort holds the key to reduce this frustration, including aiding in maintenance of OpenComputers Lua assets themselves.

If anyone has the time and patience to manually write such annotations or generate them from ocdoc.cil.li, please let yourselves be known. Such documentation efforts should be folded into the OpenComputers project so it can stay standardized and up to date.