search

renoise / definitions

LuaCATS definitions for the Renoise Lua API
MIT License
6 stars 4 forks source link

Cleanup definitions #35

Closed unlessgames closed 2 months ago

unlessgames commented 3 months ago

I've been working on the API doc gen and realized these separate instances have no actual purpose in the definition files and just add noise both to the json export and the lua files as the same class is referenced twice.

I am talking about stuff like this

---Some description
---@class renoise.Something
renoise.Something = {}

---@class renoise.Something
---@field some1 ...
---@field some2 ...

The actual class definition happens in the second section, whatever comment preceded the first should go to above the second and the first block should be deleted. The assignment should move to the bottom of the class def so that we are left with ->

---Some description
---@class renoise.Something
---@field some1 ...
---@field some2 ...
renoise.Something = {}

Am I overlooking something here? If not and it's ok, I'd go ahead and do the above edit to the files.

emuell commented 3 months ago

Yes, those are redundant - a leftover from the old API documentation structure - and can simply be removed.

The enum constants, such as 

---@enum renoise.Song.SubColumnType
renoise.Song = { ... }

may still be problematic then. I've got no clue how else to define them in LuaLS.

unlessgames commented 3 months ago

The enums are better as they are exported as a separate type, just a bit confusing since .SubColumnType doesn't actually exist in code.

Speaking of how to define things, the JSON simply doesn't contain the values of constants that are defined outside of enums on a class, only the identifier is there. For example renoise.InstrumentPhrase.MAX_NUMBER_OF_LINES is in the output but its value, 512 is not.

The values of enums need to be parsed from a raw lua string (we could just print this as a markdown codeblock as well) but at least they are included.

emuell commented 3 months ago

For example renoise.InstrumentPhrase.MAX_NUMBER_OF_LINES is in the output but its value, 512 is not.

I think this is good, as it encourages you to actually use the constant instead of the magic number. In the old docs they were actually skipped for this reason, but in the new docs I had to assign some values to make it a valid enum in LuaLS.