MightyPirates
Adoption of Teal/EmmyLua typing anotation
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.
This sounds like a good idea, with the minor caveat that increasing .lua file size directly adds to the hard drive usage in OpenComputers; adding too many annotations to the OS itself may prompt a need to rebalance the mod's default hard disk sizes.
Ideally, it would be ocdoc.cil.li pages and mod-bundled Markdown documentation which are generated from such annotations.
It is best to create a new document repository for maintenance for this requirement, and do not add it to the existing openos code, because the hard disk in OC is not large.
Should I try it?
I mean, you could make it so you can download the documentation via OPPM, yea
I mean, you could make it so you can download the documentation via OPPM, yea
I finished it in one night, but it was just the most basic version, and I used multiple AIs to generate it. So the format is not very uniform, but I can't stand it anymore, the amount of OC documentation is too large.
I've attached the repo address below. Do you think there's anything else that needs to be improved?
@asiekierka I generated an EmmyLua document from ocdoc.cil.li. However, using multiple AIs resulted in inconsistent formatting. It took some time to get it working properly. What are your thoughts? Should I gradually update the earlier document to the later format?
And incorporate it into the official, generate Chinese documents, etc.
All documents have been preliminarily completed, except for a few component APIs provided by other mods. Most of them are generated by GPT from existing documentation websites. Welcome to review