Open hmans opened 2 weeks ago
I've identified one slightly annoying caveat (that the existing LuaCATS/lovr repository shares) that can't be fixed without changes to the api/init.lua
generation: there's no information about fields on classes/instances. For example, accessing the .x
field on a vec3 will always be marked with a warning because the field isn't known (and of course it will be typed unknown
.)
I'm guessing that fixing this is, theoretically, a matter of changing the api
project to also inject fields
information into the objects
entries in api/init.lua
, but I'm definitely out of my depth here. Is this even possible?
Edit: Implemented (including swizzles.) I've updated the PR description accordingly.
Summary
As discussed via Matrix, this PR adds a fresh new LuaCATS API annotations generator to this repository. Please consider this PR work in progress for the time being; I'm opening it at this point in order to discuss further work and gather feedback.
Notes
tools/generate-cats.lua
script.@examples
(with proper Lua-synatx-highlighted code blocks), and provides correct overload definitions (see below).@overload
tag, but renders multiple documentation blocks per overload as suggested by the LuaCATS documentation: "it is recommended to instead write multiple function definitions, one for each needed signature with its @param and @return annotations. This allows the functions to be as detailed as possible. Because the functions do not exist at runtime, this is acceptable."injected.lua
file containing thevec3
,Vec3
etc. globals injected fromlovr.math.*
ift.math.globals = true
. Hopefully this isn't too annoying for when folks disable that setting?@field
annotations (sourced from the newfields
property of object API definitions.)swizzles
property of the object API definitions.)Testing
To test the generated annotations in a project, point your LuaLS at it like this:
To run the generator script:
Todo
lovr.math.Vec3
and other objects from that module just won't work. The objects from all other modules appear to work fine. Only themath
module somehow is problematic..x
,.y
etc. vector fields to theapi
projectThere's probably more bits and pieces missing. Feedback welcome!