base_classes: Event: improve :extended(), clean doc-blocks. Rel…

…ates to lord-server#1558, lord-server#1565

mods/lord/Core/base_classes/src/base_classes/Event.lua

@@ -2,28 +2,34 @@ local pairs
     = pairs
 
 
---- @static
+--- @alias base_classes.Event.callback fun(...):void
+
+--- @abstract
 --- @class base_classes.Event
 local Event = {
-	Type        = {},
-	subscribers = {},
+	--- @alias base_classes.Event.Type table<string,string>
+	--- @class base_classes.Event.Type
+	Type        = nil,
+	--- @type table<string,base_classes.Event.callback[]>
+	subscribers = nil,
 }
 
---- @static
---- @return base_classes.Event
-function Event:extended(object_or_class)
-	local class = self
-	self = object_or_class or {}
-	return setmetatable(self, { __index = class} )
-end
+--- @generic GenericEvent: base_classes.Event
+--- @param child_class GenericEvent
+--- @return GenericEvent
+function Event:extended(child_class)
+	self = setmetatable(child_class or {}, { __index = self })
 
+	self.Type        = self.Type or {}
+	self.subscribers = self.subscribers or {}
 
---- @alias base_classes.Event.callback function
+	return self
+end
 
 --- @generic GenericEvent: base_classes.Event
 --- @param event string       name of event (One of `Event.Type::<const>`)
 --- @param base  GenericEvent if you want to link returned function to this `base` class|object
---- @return fun(callback:controls.callback)
+--- @return fun(callback:base_classes.Event.callback)
 function Event:on(event, base)
 	return base
 		and
@@ -37,27 +43,27 @@ function Event:on(event, base)
 end
 
 --- @param event    string name of event (One of `Event.Type::<const>`)
---- @param callback controls.callback
+--- @param callback base_classes.Event.callback
 function Event:subscribe(event, callback)
-	assert(self.Type[event], "Unknown controls.Event.Type: " .. event)
+	assert(self.Type[event], "Unknown Event.Type: " .. event)
 	assert(type(callback) == "function")
 
 	table.insert(self.subscribers[event], callback)
 end
 
 --- @private
 --- @param event string name of event (One of `Event.Type::<const>`)
---- @vararg any pass args that will be passed to subscribers callbacks. See `controls.callbacks.<func-types>`
+--- @vararg any pass args that will be passed to subscribers callbacks.
 function Event:notify(event, ...)
-	assert(self.Type[event], "Unknown controls.Event.Type: " .. event)
+	assert(self.Type[event], "Unknown Event.Type: " .. event)
 
 	for _, func in pairs(self.subscribers[event]) do
 		func(...)
 	end
 end
 
 --- @param event string name of event (One of `Event.Type::<const>`)
---- @vararg any pass args that will be passed to subscribers callbacks. See `controls.callbacks.<func-types>`
+--- @vararg any pass args that will be passed to subscribers callbacks.
 function Event:trigger(event, ...)
 	self:notify(event, ...)
 end

mods/lord/Core/base_classes/src/base_classes/Form/Event.lua

@@ -1,6 +1,20 @@
 local BaseEvent = require('base_classes.Event')
 
+
+--- @generic GenericForm: base_classes.Form.Base
+--- @alias base_classes.Form.callback.on_register fun(form:GenericForm)
+--- @alias base_classes.Form.callback.on_instance fun(form:GenericForm, player:Player, ...)
+--- @alias base_classes.Form.callback.on_open     fun(form:GenericForm)
+--- @alias base_classes.Form.callback.on_close    fun(form:GenericForm)
+--- @alias base_classes.Form.callback.on_handle   fun(form:GenericForm, player:Player, fields:table)
+-- luacheck: no max line length
+--- @alias base_classes.Form.callback base_classes.Form.callback.on_register|base_classes.Form.callback.on_instance|base_classes.Form.callback.on_open|base_classes.Form.callback.on_close|base_classes.Form.callback.on_handle
+
+
+--- @generic GenericEvent: base_classes.Form.Event
 --- @class base_classes.Form.Event: base_classes.Event
+--- @field on      fun(event:string, base:GenericEvent): fun(callback:base_classes.Form.callback)
+--- @field trigger fun(event:string, ...): void
 local Event = BaseEvent:extended()
 
 --- @class base_classes.Form.Event.Type
@@ -12,14 +26,7 @@ Event.Type = {
 	on_handle   = 'on_handle',
 }
 
---- @generic GenericForm: base_classes.Form.Base
---- @alias base_classes.Form.callback.on_register fun(form:GenericForm)
---- @alias base_classes.Form.callback.on_instance fun(form:GenericForm, player:Player, ...)
---- @alias base_classes.Form.callback.on_open     fun(form:GenericForm)
---- @alias base_classes.Form.callback.on_close    fun(form:GenericForm)
---- @alias base_classes.Form.callback.on_handle   fun(form:GenericForm, player:Player, fields:table)
-
-
+--- @type table<string|base_classes.Form.Event.Type,base_classes.Form.callback[]>
 Event.subscribers = {
 	--- @type base_classes.Form.callback.on_register[]
 	on_register = {},

mods/lord/Core/controls/src/controls/Event.lua

@@ -1,5 +1,12 @@
+--- @alias controls.callbacks.OnPress fun(player:Player, key:string)
+--- @alias controls.callbacks.OnHold fun(player:Player, key:string, hold_time:number)
+--- @alias controls.callbacks.OnRelease fun(player:Player, key:string, hold_time:number)
+--- @alias controls.callback controls.callbacks.OnPress|controls.callbacks.OnHold|controls.callbacks.OnRelease
+
 
 --- @class controls.Event: base_classes.Event
+--- @field on      fun(event:string|controls.Event.Type): fun(callback:controls.callback)
+--- @field trigger fun(event:string|controls.Event.Type, ...): void
 local Event = base_classes.Event:extended()
 
 --- @class controls.Event.Type
@@ -8,12 +15,7 @@ Event.Type        = {
 	on_hold    = "on_hold",
 	on_release = "on_release",
 }
-
---- @alias controls.callbacks.OnPress fun(player:Player, key:string)
---- @alias controls.callbacks.OnHold fun(player:Player, key:string, hold_time:number)
---- @alias controls.callbacks.OnRelease fun(player:Player, key:string, hold_time:number)
---- @alias controls.callback controls.callbacks.OnPress|controls.callbacks.OnHold|controls.callbacks.OnRelease
-
+--- @type table<string,controls.callback[]>
 Event.subscribers = {
 	---@type controls.callbacks.OnPress[]
 	on_press   = {},

mods/lord/Core/wield_item/src/wield_item/Event.lua

@@ -1,16 +1,18 @@
+--- @alias wield_item.callbacks.OnIndexChange fun(player:Player, key:string)
+--- @alias wield_item.callback wield_item.callbacks.OnIndexChange
+
 
 --- @static
 --- @class wield_item.Event: base_classes.Event
+--- @field on      fun(event:string|wield_item.Event.Type): fun(callback:wield_item.callback)
+--- @field trigger fun(event:string|wield_item.Event.Type, ...): void
 local Event = base_classes.Event:extended()
 
 --- @class wield_item.Event.Type
 Event.Type  = {
 	on_index_change = "on_index_change",
 }
-
---- @alias wield_item.callbacks.OnIndexChange fun(player:Player, key:string)
---- @alias wield_item.callback wield_item.callbacks.OnIndexChange
-
+--- @type table<string,wield_item.callback[]>
 Event.subscribers = {
 	---@type wield_item.callbacks.OnIndexChange[]
 	on_index_change = {},

mods/lord/Player/clans/src/clans/Event.lua

@@ -1,3 +1,7 @@
+--- @alias clans.callbacks.OnClanOperation fun(clan:clans.Clan)
+--- @alias clans.callbacks.OnClanPlayerOperation fun(clan:clans.Clan, player_name:string)
+--- @alias clans.callback clans.callbacks.OnClanOperation|clans.callbacks.OnClanPlayerOperation
+
 
 --- @static
 --- @class clans.Event: base_classes.Event
@@ -14,11 +18,7 @@ Event.Type = {
 	on_clan_player_join    = "on_clan_player_join",
 	on_clan_player_leave   = "on_clan_player_leave",
 }
-
---- @alias clans.callbacks.OnClanOperation fun(clan:clans.Clan)
---- @alias clans.callbacks.OnClanPlayerOperation fun(clan:clans.Clan, player_name:string)
---- @alias clans.callback clans.callbacks.OnClanOperation|clans.callbacks.OnClanPlayerOperation
-
+--- @type table<string,clans.callback[]>
 Event.subscribers = {
 	---@type clans.callbacks.OnClanOperation[]
 	on_clan_created = {},