Update

druid/druid.lua

@@ -1,53 +1,6 @@
--- Copyright (c) 2021 Maksim Tuprikov <[email protected]>. This code is licensed under MIT license
-
---- Druid UI Component Framework.
--- <b># Overview #</b>
---
--- Druid - powerful Defold component UI library. Use basic and extended
--- Druid components or make your own game-specific components to make
--- amazing GUI in your games.
---
--- To start using Druid, please refer to the Usage section below.
---
--- <b># Notes #</b>
---
--- • Each Druid instance maintains the self context from the constructor and passes it to each Druid callback.
---
--- See next: DruidInstance
---
--- @usage
--- local druid = require("druid.druid")
---
--- local function on_play(self)
---     print("Gonna play!")
--- end
---
--- function init(self)
---     self.druid = druid.new(self)
---     self.druid:new_button("button_play", on_play)
--- end
---
--- function final(self)
---     self.druid:final()
--- end
---
--- function update(self, dt)
---     self.druid:update(dt)
--- end
---
--- function on_message(self, message_id, message, sender)
---     self.druid:on_message(message_id, message, sender)
--- end
---
--- function on_input(self, action_id, action)
---     return self.druid:on_input(action_id, action)
--- end
---
--- @module Druid
-
 local const = require("druid.const")
-local base_component = require("druid.component")
 local settings = require("druid.system.settings")
+local base_component = require("druid.component")
 local druid_instance = require("druid.system.druid_instance")
 
 local default_style = require("druid.styles.default.style")
@@ -73,9 +26,9 @@ end
 
 
 ---Register a new external Druid component.
----You can register your own components to make new alias: the druid:new_{name} function.
----For example, if you want to register a component called "my_component", you can create it using druid:new_my_component(...).
----This can be useful if you have your own "basic" components that you don't want to re-create each time.
+---Register component just makes the druid:new_{name} function.
+---For example, if you register a component called "my_component", you can create it using druid:new_my_component(...).
+---This can be useful if you have your own "basic" components that you don't want to require in every file.
 ---@param name string Module name
 ---@param module table Lua table with component
 function M.register(name, module)

druid/event.lua

@@ -1,15 +1,6 @@
--- Copyright (c) 2021 Maksim Tuprikov <[email protected]>. This code is licensed under MIT license
-
---- Druid Event Module
---
--- The Event module provides a simple class for handling callbacks. It is used in many Druid components.
---
--- You can subscribe to an event using the `:subscribe` method and unsubscribe using the `:unsubscribe` method.
--- @module DruidEvent
--- @alias druid.event
-
 ---@class druid.event
 local M = {}
+
 M.COUNTER = 0
 
 -- Forward declaration
@@ -20,13 +11,11 @@ local pcall = pcall
 local tinsert = table.insert
 local tremove = table.remove
 
---- DruidEvent constructor
--- @tparam function|nil callback Subscribe the callback on new event, if callback exist
--- @tparam any|nil callback_context Additional context as first param to callback call
--- @usage
--- local Event = require("druid.event")
--- ...
--- local event = Event(callback)
+--- Return new event instance
+---@param callback fun()|nil Subscribe the callback on new event, if callback exist
+---@param callback_context any|nil Additional context as first param to callback call
+---@return druid.event
+---@nodiscard
 function M.create(callback, callback_context)
 	local instance = setmetatable({}, EVENT_METATABLE)
 
@@ -40,9 +29,8 @@ end
 
 
 --- Check is event subscribed.
--- @tparam DruidEvent self DruidEvent
--- @tparam function callback Callback itself
--- @tparam any|nil callback_context Additional context as first param to callback call
+---@param callback fun() Callback itself
+---@param callback_context any|nil Additional context as first param to callback call
 -- @treturn boolean, number|nil @Is event subscribed, return index of callback in event as second param
 function M:is_subscribed(callback, callback_context)
 	if #self == 0 then
@@ -60,18 +48,10 @@ function M:is_subscribed(callback, callback_context)
 end
 
 
---- Subscribe callback on event
--- @tparam DruidEvent self DruidEvent
--- @tparam function callback Callback itself
--- @tparam any|nil callback_context Additional context as first param to callback call, usually it's self
--- @treturn boolean True if callback was subscribed
--- @usage
--- local function on_long_callback(self)
---     print("Long click!")
--- end
--- ...
--- local button = self.druid:new_button("button", callback)
--- button.on_long_click:subscribe(on_long_callback, self)
+---Subscribe callback on event
+---@param callback fun() Callback itself
+---@param callback_context any|nil Additional context as first param to callback call, usually it's self
+---@return boolean
 function M:subscribe(callback, callback_context)
 	assert(type(self) == "table", "You should subscribe to event with : syntax")
 	assert(callback, "A function must be passed to subscribe to an event")
@@ -85,16 +65,10 @@ function M:subscribe(callback, callback_context)
 end
 
 
---- Unsubscribe callback on event
--- @tparam DruidEvent self DruidEvent
--- @tparam function callback Callback itself
--- @tparam any|nil callback_context Additional context as first param to callback call
--- @usage
--- local function on_long_callback(self)
---     print("Long click!")
--- end
--- ...
--- button.on_long_click:unsubscribe(on_long_callback, self)
+---Unsubscribe callback on event
+---@param callback fun() Callback itself
+---@param callback_context any|nil Additional context as first param to callback call
+---@return boolean
 function M:unsubscribe(callback, callback_context)
 	assert(callback, "A function must be passed to subscribe to an event")
 
@@ -108,30 +82,21 @@ function M:unsubscribe(callback, callback_context)
 end
 
 
---- Return true, if event have at lease one handler
--- @tparam DruidEvent self DruidEvent
--- @treturn boolean True if event have handlers
--- @usage
--- local is_long_click_handler_exists = button.on_long_click:is_exist()
+---Return true, if event have at lease one handler
+---@return boolean
 function M:is_exist()
 	return #self > 0
 end
 
 
---- Return true, if event not have handler
---- @tparam DruidEvent self DruidEvent
---- @treturn boolean True if event not have handlers
---- @usage
---- local is_long_click_handler_not_exists = button.on_long_click:is_empty()
+---Return true, if event not have handler
+---@return boolean True if event not have handlers
 function M:is_empty()
 	return #self == 0
 end
 
 
---- Clear the all event handlers
--- @tparam DruidEvent self DruidEvent
--- @usage
--- button.on_long_click:clear()
+---Clear the all event handlers
 function M:clear()
 	for index = #self, 1, -1 do
 		self[index] = nil
@@ -140,13 +105,8 @@ end
 
 
 --- Trigger the event and call all subscribed callbacks
--- @tparam DruidEvent self DruidEvent
--- @tparam any ... All event params
--- @usage
--- local Event = require("druid.event")
--- ...
--- local event = Event()
--- event:trigger("Param1", "Param2")
+---@param ... any All event params
+---@return any result Last returned value from subscribers
 function M:trigger(...)
 	if #self == 0 then
 		return
@@ -163,10 +123,9 @@ function M:trigger(...)
 end
 
 
--- @tparam table callback Callback data {function, context}
--- @tparam any ... All event params
--- @treturn any Result of the callback
--- @local
+---@param callback table Callback data {function, context}
+---@param ... any All event params
+---@return any result Result of the callback
 function M:call_callback(callback, ...)
 	local event_callback = callback[1]
 	local event_callback_context = callback[2]