demiurgequantified/pzeventdoc

Tool for generating Lua documentation for Project Zomboid events and hooks

pzeventdoc's Issues

Complete Rosetta conversion

We now read Rosetta formatted files exclusively, but the new features of Rosetta aren't actually utilised:

In the Rosetta schema descriptions can be added to parameters. It's not clear yet how these can be utilised: the current method for formatting function signatures doesn't have any support for it. It could be neatly formatted into the function descriptions instead if it can't be attached to the parameters directly. How the markdown generator formats parameters will need to be rethought too. These also need to actually be documented (#6).

The Rosetta schema also allows events to have names assigned, presumably for translation purposes. This name is currently ignored. How it will be presented in typings will need to be considered.

Expand parameter documentation

Rosetta adds support for parameter descriptions - this needs code support (#4) but it also needs someone to go through and actually write descriptions for them. Previously an effort was made to make this information obvious from the description, so it would mainly comprise of moving information from there.

Event-specific class definitions are duplicated

extra.lua is used to define classes that aren't part of the main schema but are needed to describe the values passed by events. The contents of this file is duplicated into every lua file generated, creating multiple definitions.

Use aliasing for callbacks

Using type aliases for callbacks would allow users to annotate their callbacks as that type, simplifying type checking. Previously this wasn't done as I was unsure if EmmyLua supports it, but the target platform is now LuaCATS.

Event descriptions

OnAIStateChange also triggers for remote players near the local players.

OnObjectAboutToBeRemoved: in my experience this:

---Fires before a tile object is removed from the square, either because it has been destroyed or picked up.

would be more accurate: than this:

---Fires before a tile object is removed from the world, either because it has been destroyed or because it has been unloaded.

No markdown documentation for event-specific class definitions

There should be some description of the 'fake' classes used by events in the markdown format.

Rosetta patch support

Rosetta supports 'patch' files for translating data. There's no support on the PZEventDoc end for this - it would likely be simple enough to merge the data from the patch file over the base data before starting generation.

Miscellaneous TODOs left over

There's a few events that I couldn't work out the exact trigger circumstances for:

• OnGetDBSchema
• OnGetTableResult
• OnReceiveUserlog
• onUpdateIcon

Additionally, these events have some unclear parameters:

• OnMouseMove
• OnServerWorkshopItems

If somebody could take a look at any of these, it'd be greatly appreciated!

Steam events are undocumented

Some of the Steam integration events are undocumented, specifically:

• OnSteamRulesRefreshComplete
• OnSteamServerResponded
• OnSteamServerResponded2

These events are pretty much relayed from Steam, so someone needs to dive into the Steamworks API to work out when they get called and what their parameters actually represent.

OnConnectionStateChanged documentation incomplete after Rosetta conversion

The Rosetta schema doesn't support multiple signatures for an event callback. The only event that actually used this is OnConnectionStateChanged, so that event's documentation needs updating to convey all information in just one signature.

Create callback types for script functions

While strictly out of the scope of events, Umbrella doesn't currently cover script functions, and this module suits it best as it already deals with callback types. Since I already documented these and their types in PZModdingGuides, it should be pretty easy to have type aliases generated for these too. Rosetta's schema may need to be altered slightly for this.