Inherited method overloading

[Derpius]

I'm writing docgen for a game's scripting API that implements an event system passing a string as the event name and a callback function with event specific signatures

Additionally, classes that implement the event subscribe method inherit events from their base classes (if they have any)

I tried the annotations below however calling Subscribe on an instance of B will only show BEvent, completely overwriting the definition in class A

---@class A
local a = {}

---Subscribe to an event
---@param eventName string
---@param callback function
---@overload fun(self: A, eventName: "AEvent", callback: fun())
function a:Subscribe(eventName, callback) end

---@class B : A
local b = {}

---Subscribe to an event
---@param eventName string
---@param callback function
---@overload fun(self: B, eventName: "BEvent", callback: fun(arg: string))
function b:Subscribe(eventName, callback) end

Is there any way to overload a base class function without overwriting it? (that also works with multiple inheritance)

[carsakiller]

This is an interesting use case for classes and inheritance.... I am confused with how this is all fits together.

If a:Subscribe and b:Subscribe do the exact same thing, you wouldn't need b:Subscribe as a:Subscribe will be inherited and will be useable in class B.

If you do need both a:Subscribe and b:Subscribe, there is no actual overloading in Lua, the Subscribe method from class A will always be overwritten by the method in class B when inheriting. You would probably have to wrap it:

function b:Subscribe(event, callback)
    if event == "AEvent" then
        return a:Subscribe(event, callback)
    end
    --- do b:Subscribe stuff...
end

[Derpius]

It's not the function itself that needs redeclaring per-se, it's the additional events the derived class implements

If there's no way of doing this then I can handle inheritance myself when generating the annotations, and just copy the events from the base classes to the new function def

[Derpius]

An example of the event inheritance would be https://docs.nanos.world/docs/scripting-reference/classes/static-mesh#events

[Derpius]

Also the overloading is just to be able to type event callbacks, the event system itself is implemented C++ side

[sumneko]

It is not supported, because in most cases, we want the sub-class cover the same name field in parent-class.
Maybe we can only handle your needs by adding a special annotation for the field.

[carsakiller]

When in doubt, use @alias 😄

---@alias BaseActorEvents
---| '"Destroy"'
---| '"Spawn"'
---| '"ValueChange"'

---@class BaseActor
local BaseActor = {}

---Subscribe to an event
---@param eventName BaseActorEvents
---@param callback fun()
function BaseActor:Subscribe(eventName, callback) end


---@alias StaticMeshEvents
---| '"TakeDamage"'

---@class StaticMesh : BaseActor
local StaticMesh = {}

---Subscribe to an event
---@param eventName BaseActorEvents | StaticMeshEvents
---@param callback fun(arg: string)
function StaticMesh:Subscribe(eventName, callback) end

So long as the functionality of StaticMesh:Subscribe() can completely overwrite BaseActor:Subscribe(), the above should work documentation-wise.

[Derpius]

Does that support different callback signatures for each event?
Looks like all callbacks on StaticMesh will have the fun(arg: string) signature

Using StaticMesh and Actor as an example:
Event Spawn on Actor has a callback signature fun(self: Actor)
Event ValueChange on Actor has a callback signature fun(self: Actor, key: string, value: any)
Event TakeDamage on StaticMesh has a callback signature fun(self: StaticMesh, damage: number, bone: string, type: DamageType, from_direction: Vector, instigator: Player, causer: any)

[sumneko]

Because I was busy with job of employers recently, I wanted to put on this request.
What is interesting is that I just encountered this request in the job today, so I decided to implement this feature in next version.

[carsakiller]

I think function overloading needs some work. If you use @overload you can't describe any params, returns, or the function itself. If you define multiple signatures, you are warned that they are duplicates and then completion doesn't really work. I am going to open an issue about this as I think it is its own larger problem.