WIP: Generate LuaCATS annotations

[hmans]

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

• This PR looks pretty hefty because it also includes the generated files for reference. The actual work happens in the new tools/generate-cats.lua script.
• I believe the iteration of the annotations generated here is significantly more complete than the one that currently lives in the LuaCATS repository, even beyond simply updating them to a newer version of the API. It leans a little more into the markdown-based help syntax supported by editors like VS Code, includes @examples (with proper Lua-synatx-highlighted code blocks), and provides correct overload definitions (see below).
• Doesn't use the @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."
• Generates an extra injected.lua file containing the vec3, Vec3 etc. globals injected from lovr.math.* if t.math.globals = true. Hopefully this isn't too annoying for when folks disable that setting?
• If the code is even supposed to write the files into this repository is to be discussed. Generally speaking, I'm happy to hear what kind of setup would work best and then go for that.
• New: Supports @field annotations (sourced from the new fields property of object API definitions.)
• New: Auto-generates swizzles for vector objects (steered through the new swizzles property of the object API definitions.)

Testing

To test the generated annotations in a project, point your LuaLS at it like this:

{
  "Lua.workspace.library": [
    "/path/to/lovr-docs/cats"
  ]
}

To run the generator script:

# It's important to do this from the repo root
lua tools/generate-cats.lua

Todo

• [x] Document modules
• [x] Document functions
• [x] Document objects
• [x] Document enums
• [x] Document callbacks
• [x] Document main module
• [x] BUG: lovr.math.Vec3 and other objects from that module just won't work. The objects from all other modules appear to work fine. Only the math module somehow is problematic.
• [x] Document math globals that can be optionally injected
• [x] Add .x, .y etc. vector fields to the api project
• [x] Generate properties for LuaCATS
• [x] Experiment: generate all legal swizzles for the vector classes
• [ ] Decide on where this code (and its output) should actually go

There's probably more bits and pieces missing. Feedback welcome!

[hmans]

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.

[Starkium]

what's the status on this? I still get warnings about vec4 and mat4

[bjornbytes]

I added a generator system to the docs generator.

• There is a "Lua" generator that serializes the API table to init.lua.
• I merged this script (with you as a Co-Author) as a new "CATS" generator that writes a library folder with LuaCATS definition files.

Remaining plan is as follows:

• Add a GitHub Actions workflow that runs the CATS generator when api files are changed and commits the library and config.json files to a cats branch.
• Submit a pull request to LLS-Addons to change the lovr submodule to point at the cats branch of lovr-docs. We'll submit a PR to bump the revision whenever a new LÖVR version is released. People that want to use the nightly build can pull the cats branch of lovr-docs manually.
• Add an "Editor Setup" guide that explains how to set all of this up!

Thank you for contributing this! It's great to finally have it merged.