Annotation typos and outdated meta information

[astrochili]

Fixing annotation typos and outdated meta information requires edits to the Defold source code, as this is the main source of documentation generation.

This issue is an attempt to collect that kind of bugs in one place and prepare pull requests to Defold batchwise. So feel free to share any annotation issues here. It will be more useful than fixing these bugs locally or just ignoring them.

[swajj]

This may be a Defold doc bug as well? particlefx.stop is annotated with a required options parameter, but it is actually optional as seen at https://defold.com/manuals/particlefx/?q=particlefx.stop#controlling-a-particle-effect - however the Defold API reference does NOT indicate it is optional at the moment.

---Stopping a particle FX does not remove already spawned particles.
---Which particle FX to stop is identified by the URL.
---@param url string|hash|url the particle fx that should stop playing
---@param options table Options when stopping the particle fx. Supported options:
---
---boolean clear: instantly clear spawned particles
---
function particlefx.stop(url, options) end

[swajj]

The annotations are missing operators for vector3/4.

I had these added to my custom copy of what you're currently storing in types.lua, they work for me to prevent things like the above:

---@class vector3
---@operator sub(vector3): vector3
---@operator add(vector3): vector3
---@operator mul(number): vector3
---@operator unm: vector3

---@class vector4
---@operator sub(vector4): vector4
---@operator add(vector4): vector4
---@operator mul(number): vector4
---@operator unm: vector4

[Jerakin]

gui.is_enabled() should have the second argument as optional.

[Jerakin]

gui.set_text() should also accepts integers.

[astrochili]

Prepared everything mentioned above in this commit - astrochili/defold@6637dec.

Waiting for a while, in case @Jerakin finds something else, and I'll send the PR to Defold.

Also I added operators for vector3/4 and matrix4 defenition to this repository.

[Jerakin]

Can the "standard" functions within Defold be annotated?

I am using a my template editor extension currently when creating new files to get the annotations but would be neat if some basic ones could be automatic, (I bet the action table would be hard) - of course there isn't much to annotate, but if possible why not :)

[astrochili]

To be honest, I don't know how to do it globally, as each update function has its own file context... and at the same time they are global dublicates for LLS. This requires experimentation.

But in templates you can of course just write:

---@param self table (or your local `SCRIPT_NAME.self` class?)
---@param dt number
function update(self, dt)
  ...
end

[astrochili]

Created PR to Defold defold/defold#8776

[astrochili]

Updated the 1.7.0 release with all these fixes.
Also added a lot of known table defenitions according #1.

Feel free to tell me about 'yellow underlines' if you see them. I may have made mistakes in tables or annotations, the edit was a major one.

[Jerakin]

gui.set_parent(node, parent, keep_scene_transform) should accepts nil as parent. Supplying nil "parents" it to the scene (i.e remove the parent).

[astrochili]

gui.set_parent(node, parent, keep_scene_transform) should accepts nil as parent. Supplying nil "parents" it to the scene (i.e remove the parent).

• Added PR Annotated optional params in gui.set_parent defold/defold#8794
• Updated manually 1.7.0 annotations release.

[Insality]

sys.reboot params should be string|nil

---@param arg1 string argument 1
---@param arg2 string argument 2
---@param arg3 string argument 3
---@param arg4 string argument 4
---@param arg5 string argument 5
---@param arg6 string argument 6
function sys.reboot(arg1, arg2, arg3, arg4, arg5, arg6) end

[astrochili]

sys.reboot params should be string|nil

---@param arg1 string argument 1
---@param arg2 string argument 2
---@param arg3 string argument 3
---@param arg4 string argument 4
---@param arg5 string argument 5
---@param arg6 string argument 6
function sys.reboot(arg1, arg2, arg3, arg4, arg5, arg6) end

Interesting. Are you sure? I am not good at c++, but in the source code some 6 arguments are processed.

[astrochili]

Ah okay, sorry, just need to add |nil! 👍

[astrochili]

sys.reboot params should be string|nil

Added PR defold/defold#8976
Updated manually 1.8.0 annotations release.