Update docs

druid/extended/container.lua

@@ -30,24 +30,25 @@ local CORNER_PIVOTS = {
 ---@field DRAGGABLE_CORNER_SIZE vector3 Size of box node for debug draggable corners
 ---@field DRAGGABLE_CORNER_COLOR vector4 Color of debug draggable corners
 
+---The component used for managing the size and positions with other containers relations to create a adaptable layouts
 ---@class druid.container: druid.component
----@field node node
----@field druid druid.instance
----@field node_offset vector4
----@field origin_size vector3
----@field size vector3
----@field origin_position vector3
----@field position vector3
----@field pivot_offset vector3
----@field center_offset vector3
----@field mode string
----@field fit_size vector3
----@field min_size_x number|nil
----@field min_size_y number|nil
----@field on_size_changed event fun(self: druid.container, size: vector3)
----@field _parent_container druid.container
----@field _containers table
----@field _draggable_corners table
+---@field node node The gui node
+---@field druid druid.instance The druid instance
+---@field node_offset vector4 The node offset
+---@field origin_size vector3 The origin size
+---@field size vector3 The current size
+---@field origin_position vector3 The origin position
+---@field position vector3 The current position
+---@field pivot_offset vector3 The pivot offset
+---@field center_offset vector3 The center offset
+---@field mode string The layout mode
+---@field fit_size vector3 The fit size
+---@field min_size_x number|nil The minimum size x
+---@field min_size_y number|nil The minimum size y
+---@field on_size_changed event fun(self: druid.container, size: vector3) The event triggered when the size changes
+---@field _parent_container druid.container The parent container
+---@field _containers table The containers
+---@field _draggable_corners table The draggable corners
 local M = component.create("container")
 
 
@@ -106,6 +107,7 @@ function M:on_remove()
 end
 
 
+---Refresh the origins of the container, origins is the size and position of the container when it was created
 function M:refresh_origins()
 	self.origin_size = gui.get_size(self.node)
 	self.origin_position = gui.get_position(self.node)
@@ -113,7 +115,8 @@ function M:refresh_origins()
 end
 
 
----@param pivot constant
+---Set the pivot of the container
+---@param pivot constant The pivot to set
 function M:set_pivot(pivot)
 	gui.set_pivot(self.node, pivot)
 	self.pivot_offset = helper.get_pivot_offset(pivot)
@@ -121,7 +124,8 @@ function M:set_pivot(pivot)
 end
 
 
----@param style druid.container.style
+---Set the style of the container
+---@param style druid.container.style The style to set
 function M:on_style_change(style)
 	self.style = {
 		DRAGGABLE_CORNER_SIZE = style.DRAGGABLE_CORNER_SIZE or vmath.vector3(24, 24, 0),
@@ -131,8 +135,8 @@ end
 
 
 ---Set new size of layout node
----@param width number|nil
----@param height number|nil
+---@param width number|nil The width to set
+---@param height number|nil The height to set
 ---@param anchor_pivot constant|nil If set will keep the corner possition relative to the new size
 ---@return druid.container Container
 function M:set_size(width, height, anchor_pivot)
@@ -174,13 +178,16 @@ function M:set_size(width, height, anchor_pivot)
 end
 
 
+---Get the position of the container
+---@return vector3 position The position of the container
 function M:get_position()
 	return self._position
 end
 
 
----@param pos_x number
----@param pos_y number
+---Set the position of the container
+---@param pos_x number The x position to set
+---@param pos_y number The y position to set
 function M:set_position(pos_x, pos_y)
 	if self._position.x == pos_x and self._position.y == pos_y then
 		return
@@ -192,23 +199,23 @@ function M:set_position(pos_x, pos_y)
 end
 
 
----Get current size of layout node
----@return vector3 size
+---Get the current size of the layout node
+---@return vector3 size The current size of the layout node
 function M:get_size()
 	return vmath.vector3(self.size)
 end
 
 
----Get current scale of layout node
----@return vector3 scale
+---Get the current scale of the layout node
+---@return vector3 scale The current scale of the layout node
 function M:get_scale()
 	return helper.get_scene_scale(self.node, true) --[[@as vector3]]
 end
 
 
 ---Set size for layout node to fit inside it
----@param target_size vector3
----@return druid.container Container
+---@param target_size vector3 The target size to fit into
+---@return druid.container self Current container instance
 function M:fit_into_size(target_size)
 	self.fit_size = target_size
 	self:refresh()
@@ -218,7 +225,7 @@ end
 
 
 ---Set current size for layout node to fit inside it
----@return druid.container Container
+---@return druid.container self Current container instance
 function M:fit_into_window()
 	return self:fit_into_size(vmath.vector3(gui.get_width(), gui.get_height(), 0))
 end
@@ -440,7 +447,7 @@ function M:update_child_containers()
 end
 
 
----@return druid.container Container
+---@return druid.container self Current container instance
 function M:create_draggable_corners()
 	self:clear_draggable_corners()
 
@@ -470,7 +477,7 @@ function M:create_draggable_corners()
 end
 
 
----@return druid.container Container
+---@return druid.container self Current container instance
 function M:clear_draggable_corners()
 	for index = 1, #self._draggable_corners do
 		local drag_component = self._draggable_corners[index]
@@ -523,7 +530,7 @@ end
 
 ---Set node for layout node to fit inside it. Pass nil to reset
 ---@param node string|node The node_id or gui.get_node(node_id)
----@return druid.container Layout
+---@return druid.container self Current container instance
 function M:fit_into_node(node)
 	self._fit_node = self:get_node(node)
 	self:refresh_scale()
@@ -531,8 +538,10 @@ function M:fit_into_node(node)
 end
 
 
----@param min_size_x number|nil
----@param min_size_y number|nil
+---Set the minimum size of the container
+---@param min_size_x number|nil The minimum size x
+---@param min_size_y number|nil The minimum size y
+---@return druid.container self Current container instance
 function M:set_min_size(min_size_x, min_size_y)
 	self.min_size_x = min_size_x or self.min_size_x
 	self.min_size_y = min_size_y or self.min_size_y

druid/extended/data_list.lua

@@ -3,25 +3,26 @@ local helper = require("druid.helper")
 local component = require("druid.component")
 local event = require("event.event")
 
+---The component used for managing a list of data with a scrollable view, used to manage huge list data and render only visible elements
 ---@class druid.data_list: druid.component
----@field scroll druid.scroll
----@field grid druid.grid
----@field on_scroll_progress_change event
----@field on_element_add event
----@field on_element_remove event
----@field top_index number
----@field last_index number
----@field scroll_progress number
----@field private _create_function function
----@field private _is_use_cache boolean
----@field private _cache table
----@field private _data table
----@field private _data_visual table
+---@field scroll druid.scroll The scroll instance for Data List component
+---@field grid druid.grid The StaticGrid or DynamicGrid instance for Data List component
+---@field on_scroll_progress_change event The event triggered when the scroll progress changes
+---@field on_element_add event The event triggered when a new element is added
+---@field on_element_remove event The event triggered when an element is removed
+---@field top_index number The top index of the visible elements
+---@field last_index number The last index of the visible elements
+---@field scroll_progress number The scroll progress
+---@field private _create_function function The create function callback(self, data, index, data_list). Function should return (node, [component])
+---@field private _is_use_cache boolean Use cache version of DataList. Requires make setup of components in on_element_add callback and clean in on_element_remove
+---@field private _cache table The cache table
+---@field private _data table The data table
+---@field private _data_visual table The data visual table
 local M = component.create("data_list")
 
 
 ---@param scroll druid.scroll The Scroll instance for Data List component
----@param grid druid.grid The StaticGrid} or @{DynamicGrid instance for Data List component
+---@param grid druid.grid The StaticGrid instance for Data List component
 ---@param create_function function The create function callback(self, data, index, data_list). Function should return (node, [component])
 function M:init(scroll, grid, create_function)
 	self.scroll = scroll
@@ -56,9 +57,9 @@ function M:on_remove()
 end
 
 
----Set refresh function for DataList component
----@param is_use_cache boolean Use cache version of DataList. Requires make setup of components in on_element_add callback and clean in on_element_remove
----@return druid.data_list Current DataList instance
+---Set use cache version of DataList. Requires make setup of components in on_element_add callback and clean in on_element_remove
+---@param is_use_cache boolean Use cache version of DataList
+---@return druid.data_list self Current DataList instance
 function M:set_use_cache(is_use_cache)
 	self._is_use_cache = is_use_cache
 	return self
@@ -67,7 +68,7 @@ end
 
 ---Set new data set for DataList component
 ---@param data table The new data array
----@return druid.data_list Current DataList instance
+---@return druid.data_list self Current DataList instance
 function M:set_data(data)
 	self._data = data or {}
 	self:_refresh()
@@ -77,50 +78,62 @@ end
 
 
 ---Return current data from DataList component
----@return table The current data array
+---@return table data The current data array
 function M:get_data()
 	return self._data
 end
 
 
----Add element to DataList. Currenly untested
----@param data table
----@param index number|nil
+---Add element to DataList
+---@param data table The data to add
+---@param index number|nil The index to add the data at
 ---@param shift_policy number|nil The constant from const.SHIFT.*
+---@return druid.data_list self Current DataList instance
 function M:add(data, index, shift_policy)
 	index = index or #self._data + 1
 	shift_policy = shift_policy or const.SHIFT.RIGHT
 
 	helper.insert_with_shift(self._data, data, index, shift_policy)
 	self:_refresh()
+
+	return self
 end
 
 
----Remove element from DataList. Currenly untested
----@param index number|nil
+---Remove element from DataList
+---@param index number|nil The index to remove the data at
 ---@param shift_policy number|nil The constant from const.SHIFT.*
+---@return druid.data_list self Current DataList instance
 function M:remove(index, shift_policy)
 	helper.remove_with_shift(self._data, index, shift_policy)
 	self:_refresh()
+
+	return self
 end
 
 
----Remove element from DataList by data value. Currenly untested
----@param data table
+---Remove element from DataList by data value
+---@param data table The data to remove
 ---@param shift_policy number|nil The constant from const.SHIFT.*
+---@return druid.data_list self Current DataList instance
 function M:remove_by_data(data, shift_policy)
 	local index = helper.contains(self._data, data)
 	if index then
 		helper.remove_with_shift(self._data, index, shift_policy)
 		self:_refresh()
 	end
+
+	return self
 end
 
 
 ---Clear the DataList and refresh visuals
+---@return druid.data_list self Current DataList instance
 function M:clear()
 	self._data = {}
 	self:_refresh()
+
+	return self
 end
 
 
@@ -151,7 +164,7 @@ end
 
 
 ---Return all currenly created components in DataList
----@return druid.component[] List of created nodes
+---@return druid.component[] components List of created components
 function M:get_created_components()
 	local components = {}
 
@@ -164,7 +177,7 @@ end
 
 
 ---Instant scroll to element with passed index
----@param index number
+---@param index number The index to scroll to
 function M:scroll_to_index(index)
 	local pos = self.grid:get_pos(index)
 	self.scroll:scroll_to(pos)
@@ -172,7 +185,7 @@ end
 
 
 ---Add element at passed index using cache or create new
----@param index number
+---@param index number The index to add the element at
 ---@private
 function M:_add_at(index)
 	if self._data_visual[index] then
@@ -205,7 +218,7 @@ end
 
 
 ---Remove element from passed index and add it to cache if applicable
----@param index number
+---@param index number The index to remove the element at
 ---@private
 function M:_remove_at(index)
 	self.grid:remove(index, const.SHIFT.NO_SHIFT)

druid/extended/hotkey.lua

@@ -5,12 +5,13 @@ local component = require("druid.component")
 ---@class druid.hotkey.style
 ---@field MODIFICATORS string[]|hash[] The list of action_id as hotkey modificators
 
+---The component used for managing hotkeys and trigger callbacks when hotkeys are pressed
 ---@class druid.hotkey: druid.component
----@field on_hotkey_pressed event
----@field on_hotkey_released event
----@field style druid.hotkey.style
----@field private _hotkeys table
----@field private _modificators table
+---@field on_hotkey_pressed event fun(self, context, callback_argument) The event triggered when a hotkey is pressed
+---@field on_hotkey_released event fun(self, context, callback_argument) The event triggered when a hotkey is released
+---@field style druid.hotkey.style The style of the hotkey component
+---@field private _hotkeys table The list of hotkeys
+---@field private _modificators table The list of modificators
 local M = component.create("hotkey")
 
 
@@ -51,7 +52,7 @@ end
 ---Add hotkey for component callback
 ---@param keys string[]|hash[]|string|hash that have to be pressed before key pressed to activate
 ---@param callback_argument any|nil The argument to pass into the callback function
----@return druid.hotkey Current instance
+---@return druid.hotkey self Current instance
 function M:add_hotkey(keys, callback_argument)
 	keys = keys or {}
 	if type(keys) == "string" then
@@ -109,9 +110,9 @@ function M:on_focus_gained()
 end
 
 
----@param action_id hash|nil
----@param action action
----@return boolean
+---@param action_id hash|nil The action id
+---@param action action The action
+---@return boolean is_consume True if the action is consumed
 function M:on_input(action_id, action)
 	if not action_id then
 		return false
@@ -167,8 +168,8 @@ end
 
 
 ---If true, the callback will be triggered on action.repeated
----@param is_enabled_repeated bool The flag value
----@return druid.hotkey
+---@param is_enabled_repeated boolean The flag value
+---@return druid.hotkey self Current instance
 function M:set_repeat(is_enabled_repeated)
 	self._is_process_repeated = is_enabled_repeated
 	return self

druid/extended/input.lua

@@ -13,16 +13,17 @@ local utf8 = utf8 or utf8_lua
 ---@field on_unselect fun(self: druid.input, button_node: node) Callback on input field unselecting
 ---@field on_input_wrong fun(self: druid.input, button_node: node) Callback on wrong user input
 
+---The component used for managing input fields in basic way
 ---@class druid.input: druid.component
----@field on_input_select event fun(self: druid.input, input: druid.input)
----@field on_input_unselect event fun(self: druid.input, text: string, input: druid.input)
----@field on_input_text event fun(self: druid.input)
----@field on_input_empty event fun(self: druid.input)
----@field on_input_full event fun(self: druid.input)
----@field on_input_wrong event fun(self: druid.input)
----@field on_select_cursor_change event fun(self: druid.input, cursor_index: number, start_index: number, end_index: number)
----@field style table
----@field text druid.text
+---@field on_input_select event fun(self: druid.input, input: druid.input) The event triggered when the input field is selected
+---@field on_input_unselect event fun(self: druid.input, text: string, input: druid.input) The event triggered when the input field is unselected
+---@field on_input_text event fun(self: druid.input) The event triggered when the input field is changed
+---@field on_input_empty event fun(self: druid.input) The event triggered when the input field is empty
+---@field on_input_full event fun(self: druid.input) The event triggered when the input field is full
+---@field on_input_wrong event fun(self: druid.input) The event triggered when the input field is wrong
+---@field on_select_cursor_change event fun(self: druid.input, cursor_index: number, start_index: number, end_index: number) The event triggered when the cursor index is changed
+---@field style druid.input.style The style of the input component
+---@field text druid.text The text component
 local M = component.create("input")
 
 M.ALLOWED_ACTIONS = {
@@ -126,6 +127,9 @@ function M:on_style_change(style)
 end
 
 
+---@param action_id hash|nil The action id
+---@param action action The action
+---@return boolean is_consume True if the action is consumed
 function M:on_input(action_id, action)
 	if not (action_id == nil or M.ALLOWED_ACTIONS[action_id]) then
 		return false
@@ -242,9 +246,10 @@ function M:get_text_selected()
 	return utf8.sub(self.value, self.start_index + 1, self.end_index)
 end
 
+
 ---Replace selected text with new text
 ---@param text string The text to replace selected text
----@return string New input text
+---@return string new_text New input text
 function M:get_text_selected_replaced(text)
 	local left_part = utf8.sub(self.value, 1, self.start_index)
 	local right_part = utf8.sub(self.value, self.end_index + 1, utf8.len(self.value))
@@ -350,7 +355,7 @@ end
 
 
 ---Return current input field text
----@return string The current input field text
+---@return string text The current input field text
 function M:get_text()
 	if self.marked_value ~= "" then
 		return self.value .. self.marked_value
@@ -363,7 +368,7 @@ end
 ---Set maximum length for input field.
 -- Pass nil to make input field unliminted (by default)
 ---@param max_length number Maximum length for input text field
----@return druid.input Current input instance
+---@return druid.input self Current input instance
 function M:set_max_length(max_length)
 	self.max_length = max_length
 	return self
@@ -374,7 +379,7 @@ end
 -- See: https://defold.com/ref/stable/string/
 -- ex: [%a%d] for alpha and numeric
 ---@param characters string Regulax exp. for validate user input
----@return druid.input Current input instance
+---@return druid.input self Current input instance
 function M:set_allowed_characters(characters)
 	self.allowed_characters = characters
 	return self
@@ -382,7 +387,7 @@ end
 
 
 ---Reset current input selection and return previous value
----@return druid.input Current input instance
+---@return druid.input self Current input instance
 function M:reset_changes()
 	self:set_text(self.previous_value)
 	self:unselect()
@@ -394,7 +399,7 @@ end
 ---@param cursor_index number|nil Cursor index for cursor position, if nil - will be set to the end of the text
 ---@param start_index number|nil Start index for cursor position, if nil - will be set to the end of the text
 ---@param end_index number|nil End index for cursor position, if nil - will be set to the start_index
----@return druid.input Current input instance
+---@return druid.input self Current input instance
 function M:select_cursor(cursor_index, start_index, end_index)
 	local len = utf8.len(self.value)
 
@@ -416,6 +421,7 @@ end
 ---@param delta number side for cursor position, -1 for left, 1 for right
 ---@param is_add_to_selection boolean (Shift key)
 ---@param is_move_to_end boolean (Ctrl key)
+---@return druid.input self Current input instance
 function M:move_selection(delta, is_add_to_selection, is_move_to_end)
 	local len = utf8.len(self.value)
 	local cursor_index = self.cursor_index

druid/extended/lang_text.lua

@@ -2,12 +2,13 @@ local event = require("event.event")
 local component = require("druid.component")
 local settings = require("druid.system.settings")
 
+---The component used for displaying localized text, can automatically update text when locale is changed
 ---@class druid.lang_text: druid.component
----@field text druid.text
----@field node node
----@field on_change event
----@field private last_locale_args table
----@field private last_locale string
+---@field text druid.text The text component
+---@field node node The node of the text component
+---@field on_change event The event triggered when the text is changed
+---@field private last_locale_args table The last locale arguments
+---@field private last_locale string The last locale
 local M = component.create("lang_text")
 
 
@@ -38,7 +39,7 @@ end
 
 ---Setup raw text to lang_text component
 ---@param text string Text for text node
----@return druid.lang_text Current instance
+---@return druid.lang_text self Current instance
 function M:set_to(text)
 	self.last_locale = nil
 	self.text:set_text(text)
@@ -50,7 +51,7 @@ end
 
 ---Setup raw text to lang_text component
 ---@param text string Text for text node
----@return druid.lang_text Current instance
+---@return druid.lang_text self Current instance
 function M:set_text(text)
 	return self:set_to(text)
 end
@@ -59,7 +60,7 @@ end
 ---Translate the text by locale_id
 ---@param locale_id string Locale id
 ---@param ... string Optional params for string.format
----@return druid.lang_text Current instance
+---@return druid.lang_text self Current instance
 function M:translate(locale_id, ...)
 	self.last_locale_args = { ... }
 	self.last_locale = locale_id or self.last_locale
@@ -71,7 +72,7 @@ end
 
 ---Format string with new text params on localized text
 ---@param ... string Optional params for string.format
----@return druid.lang_text Current instance
+---@return druid.lang_text self Current instance
 function M:format(...)
 	self.last_locale_args = { ... }
 	self.text:set_text(settings.get_text(self.last_locale, ...) or "")

druid/extended/layout.lua

@@ -19,18 +19,19 @@ local component = require("druid.component")
 ---@field nodes_height table<node, number>
 ---@field rows druid.layout.row_data[]>
 
+---The component used for managing the layout of nodes, placing them inside the node size with respect to the size and pivot of each node
 ---@class druid.layout: druid.component
----@field node node
+---@field node node The node to manage the layout of
 ---@field rows_data druid.layout.rows_data Last calculated rows data
 ---@field is_dirty boolean
----@field entities node[]
----@field margin {x: number, y: number}
----@field padding vector4
----@field type string
----@field is_resize_width boolean
----@field is_resize_height boolean
----@field is_justify boolean
----@field on_size_changed event.on_size_changed
+---@field entities node[] The entities to manage the layout of
+---@field margin {x: number, y: number} The margin of the layout
+---@field padding vector4 The padding of the layout
+---@field type string The type of the layout
+---@field is_resize_width boolean True if the layout should resize the width of the node
+---@field is_resize_height boolean True if the layout should resize the height of the node
+---@field is_justify boolean True if the layout should justify the nodes
+---@field on_size_changed event.on_size_changed The event triggered when the size of the layout is changed
 local M = component.create("layout")
 
 
@@ -68,11 +69,15 @@ function M:update()
 end
 
 
+---@return node[] entities The entities to manage the layout of
 function M:get_entities()
 	return self.entities
 end
 
 
+---@param node node The node to set the index of
+---@param index number The index to set the node to
+---@return druid.layout self for chaining
 function M:set_node_index(node, index)
 	for i = 1, #self.entities do
 		if self.entities[i] == node then
@@ -81,12 +86,15 @@ function M:set_node_index(node, index)
 			break
 		end
 	end
+
+	return self
 end
 
 
----@param margin_x number|nil
----@param margin_y number|nil
----@return druid.layout
+---Set the margin of the layout
+---@param margin_x number|nil The margin x
+---@param margin_y number|nil The margin y
+---@return druid.layout self Current layout instance
 function M:set_margin(margin_x, margin_y)
 	self.margin.x = margin_x or self.margin.x
 	self.margin.y = margin_y or self.margin.y
@@ -96,11 +104,11 @@ function M:set_margin(margin_x, margin_y)
 end
 
 
----@param padding_x number|nil
----@param padding_y number|nil
----@param padding_z number|nil
----@param padding_w number|nil
----@return druid.layout
+---@param padding_x number|nil The padding x
+---@param padding_y number|nil The padding y
+---@param padding_z number|nil The padding z
+---@param padding_w number|nil The padding w
+---@return druid.layout self Current layout instance
 function M:set_padding(padding_x, padding_y, padding_z, padding_w)
 	self.padding.x = padding_x or self.padding.x
 	self.padding.y = padding_y or self.padding.y
@@ -112,7 +120,7 @@ function M:set_padding(padding_x, padding_y, padding_z, padding_w)
 end
 
 
----@return druid.layout
+---@return druid.layout self Current layout instance
 function M:set_dirty()
 	self.is_dirty = true
 
@@ -121,7 +129,7 @@ end
 
 
 ---@param is_justify boolean
----@return druid.layout
+---@return druid.layout self Current layout instance
 function M:set_justify(is_justify)
 	self.is_justify = is_justify
 	self.is_dirty = true
@@ -131,7 +139,7 @@ end
 
 
 ---@param type string The layout type: "horizontal", "vertical", "horizontal_wrap"
----@return druid.layout
+---@return druid.layout self Current layout instance
 function M:set_type(type)
 	self.type = type
 	self.is_dirty = true
@@ -142,7 +150,7 @@ end
 
 ---@param is_hug_width boolean
 ---@param is_hug_height boolean
----@return druid.layout
+---@return druid.layout self Current layout instance
 function M:set_hug_content(is_hug_width, is_hug_height)
 	self.is_resize_width = is_hug_width or false
 	self.is_resize_height = is_hug_height or false
@@ -154,7 +162,7 @@ end
 
 ---Add node to layout
 ---@param node_or_node_id node|string node_or_node_id
----@return druid.layout
+---@return druid.layout self Current layout instance
 function M:add(node_or_node_id)
 	-- Acquire node from entity or by id
 	local node = node_or_node_id
@@ -207,7 +215,7 @@ function M:get_content_size()
 end
 
 
----@return druid.layout
+---@return druid.layout self Current layout instance
 function M:refresh_layout()
 	local layout_node = self.node
 
@@ -349,7 +357,7 @@ function M:refresh_layout()
 end
 
 
----@return druid.layout
+---@return druid.layout self Current layout instance
 function M:clear_layout()
 	for index = #self.entities, 1, -1 do
 		self.entities[index] = nil
@@ -362,7 +370,8 @@ end
 
 
 ---@param node node
----@return number, number
+---@return number width The width of the node
+---@return number height The height of the node
 function M:get_node_size(node)
 	if not gui.is_enabled(node, false) then
 		return 0, 0

druid/extended/progress.lua

@@ -1,5 +1,4 @@
 local event = require("event.event")
-local const = require("druid.const")
 local helper = require("druid.helper")
 local component = require("druid.component")
 
@@ -7,6 +6,7 @@ local component = require("druid.component")
 ---@field SPEED number|nil Progress bas fill rate. More -> faster. Default: 5
 ---@field MIN_DELTA number|nil Minimum step to fill progress bar. Default: 0.005
 
+---The component used to manage a node as a progress bar, changing the size and scale of the node
 ---@class druid.progress: druid.component
 ---@field node node
 ---@field on_change event
@@ -17,10 +17,10 @@ local M = component.create("progress")
 
 
 ---@param node string|node Node name or GUI Node itself.
----@param key string Progress bar direction: const.SIDE.X or const.SIDE.Y
+---@param key string Progress bar direction: "x" or "y"
 ---@param init_value number|nil Initial value of progress bar. Default: 1
 function M:init(node, key, init_value)
-	assert(key == const.SIDE.X or const.SIDE.Y, "Progress bar key should be 'x' or 'y'")
+	assert(key == "x" or key == "y", "Progress bar key should be 'x' or 'y'")
 
 	self.key = key
 	self.prop = hash("scale." .. self.key)
@@ -85,27 +85,37 @@ function M:update(dt)
 end
 
 
----Fill a progress bar and stop progress animation
+---Fill the progress bar
+---@return druid.progress self Current progress instance
 function M:fill()
 	self:_set_bar_to(1, true)
+
+	return self
 end
 
 
----Empty a progress bar
+---Empty the progress bar
+---@return druid.progress self Current progress instance
 function M:empty()
 	self:_set_bar_to(0, true)
+
+	return self
 end
 
 
 ---Instant fill progress bar to value
 ---@param to number Progress bar value, from 0 to 1
+---@return druid.progress self Current progress instance
 function M:set_to(to)
 	to = helper.clamp(to, 0, 1)
 	self:_set_bar_to(to)
+
+	return self
 end
 
 
----Return current progress bar value
+---Return the current value of the progress bar
+---@return number value The current value of the progress bar
 function M:get()
 	return self.last_value
 end
@@ -114,15 +124,19 @@ end
 ---Set points on progress bar to fire the callback
 ---@param steps number[] Array of progress bar values
 ---@param callback function Callback on intersect step value
+---@return druid.progress self Current progress instance
 function M:set_steps(steps, callback)
 	self.steps = steps
 	self.step_callback = callback
+
+	return self
 end
 
 
 ---Start animation of a progress bar
 ---@param to number value between 0..1
 ---@param callback function|nil Callback on animation ends
+---@return druid.progress self Current progress instance
 function M:to(to, callback)
 	to = helper.clamp(to, 0, 1)
 	-- cause of float error
@@ -135,20 +149,26 @@ function M:to(to, callback)
 			callback(self:get_context(), to)
 		end
 	end
+
+	return self
 end
 
 
 ---Set progress bar max node size
 ---@param max_size vector3 The new node maximum (full) size
----@return druid.progress Progress
+---@return druid.progress self Current progress instance
 function M:set_max_size(max_size)
 	self.max_size[self.key] = max_size[self.key]
 	self:set_to(self.last_value)
+
 	return self
 end
 
 
 ---@private
+---@param from number The start value
+---@param to number The end value
+---@param exactly number|nil The exact value
 function M:_check_steps(from, to, exactly)
 	if not self.steps then
 		return
@@ -172,9 +192,10 @@ end
 
 
 ---@private
+---@param set_to number The value to set the progress bar to
 function M:_set_bar_to(set_to, is_silent)
 	local prev_value = self.last_value
-	local other_side = self.key == const.SIDE.X and const.SIDE.Y or const.SIDE.X
+	local other_side = self.key == "x" and "y" or "x"
 	self.last_value = set_to
 
 	local total_width = set_to * self.max_size[self.key]
@@ -206,8 +227,9 @@ function M:_set_bar_to(set_to, is_silent)
 			self.on_change:trigger(self:get_context(), self.last_value)
 		end
 	end
+
+	return self
 end
 
 
-
 return M

druid/extended/slider.lua

@@ -3,24 +3,25 @@ local helper = require("druid.helper")
 local const = require("druid.const")
 local component = require("druid.component")
 
+---The component to make a draggable node over a line with a progress report
 ---@class druid.slider: druid.component
----@field node node
----@field on_change_value event
----@field style table
----@field private start_pos vector3
----@field private pos vector3
----@field private target_pos vector3
----@field private end_pos vector3
----@field private dist vector3
----@field private is_drag boolean
----@field private value number
----@field private steps number[]
+---@field node node The node to manage the slider
+---@field on_change_value event The event triggered when the slider value changes
+---@field style table The style of the slider
+---@field private start_pos vector3 The start position of the slider
+---@field private pos vector3 The current position of the slider
+---@field private target_pos vector3 The target position of the slider
+---@field private end_pos vector3 The end position of the slider
+---@field private dist vector3 The distance between the start and end positions of the slider
+---@field private is_drag boolean True if the slider is being dragged
+---@field private value number The current value of the slider
+---@field private steps number[] The steps of the slider
 local M = component.create("slider", const.PRIORITY_INPUT_HIGH)
 
 
 ---The Slider constructor
----@param node node Gui pin node
----@param end_pos vector3 The end position of slider
+---@param node node GUI node to drag as a slider
+---@param end_pos vector3 The end position of slider, should be on the same axis as the node
 ---@param callback function|nil On slider change callback
 function M:init(node, end_pos, callback)
 	self.node = self:get_node(node)
@@ -61,6 +62,9 @@ function M:on_window_resized()
 end
 
 
+---@param action_id number The action id
+---@param action action The action table
+---@return boolean is_consumed True if the input was consumed
 function M:on_input(action_id, action)
 	if action_id ~= const.ACTION_TOUCH then
 		return false
@@ -148,6 +152,7 @@ end
 ---Set value for slider
 ---@param value number Value from 0 to 1
 ---@param is_silent boolean|nil Don't trigger event if true
+---@return druid.slider self Current slider instance
 function M:set(value, is_silent)
 	value = helper.clamp(value, 0, 1)
 	self:_set_position(value)
@@ -155,13 +160,15 @@ function M:set(value, is_silent)
 	if not is_silent then
 		self:_on_change_value()
 	end
+
+	return self
 end
 
 
 ---Set slider steps. Pin node will
 ---apply closest step position
 ---@param steps number[] Array of steps
----@return druid.slider Slider
+---@return druid.slider self Current slider instance
 function M:set_steps(steps)
 	self.steps = steps
 	return self
@@ -173,7 +180,7 @@ end
 ---move at this position and node drag will start.
 ---This function require the Defold version 1.3.0+
 ---@param input_node node|string|nil
----@return druid.slider Slider
+---@return druid.slider self Current slider instance
 function M:set_input_node(input_node)
 	if not input_node then
 		self._input_node = nil
@@ -186,14 +193,17 @@ end
 
 
 ---Set Slider input enabled or disabled
----@param is_enabled boolean
+---@param is_enabled boolean True if slider is enabled
+---@return druid.slider self Current slider instance
 function M:set_enabled(is_enabled)
 	self._is_enabled = is_enabled
+
+	return self
 end
 
 
 ---Check if Slider component is enabled
----@return boolean
+---@return boolean is_enabled True if slider is enabled
 function M:is_enabled()
 	return self._is_enabled
 end

druid/extended/swipe.lua

@@ -8,16 +8,17 @@ local component = require("druid.component")
 ---@field SWIPE_THRESHOLD number|nil Minimum distance for swipe trigger. Default: 50
 ---@field SWIPE_TRIGGER_ON_MOVE boolean|nil If true, trigger on swipe moving, not only release action. Default: false
 
+---The component to manage swipe events over a node
 ---@class druid.swipe: druid.component
----@field node node
----@field on_swipe event function(side, dist, dt), side - "left", "right", "up", "down"
----@field style table
----@field click_zone node
----@field private _trigger_on_move boolean
----@field private _swipe_start_time number
----@field private _start_pos vector3
----@field private _is_enabled boolean
----@field private _is_mobile boolean
+---@field node node The node to manage the swipe
+---@field on_swipe event fun(context, side, dist, dt) The event triggered when a swipe is detected
+---@field style druid.swipe.style The style of the swipe
+---@field click_zone node The click zone of the swipe
+---@field private _trigger_on_move boolean True if the swipe should trigger on move
+---@field private _swipe_start_time number The time the swipe started
+---@field private _start_pos vector3 The start position of the swipe
+---@field private _is_enabled boolean True if the swipe is enabled
+---@field private _is_mobile boolean True if the swipe is on a mobile device
 local M = component.create("swipe")
 
 
@@ -55,8 +56,9 @@ function M:on_style_change(style)
 end
 
 
----@param action_id hash
----@param action action
+---@param action_id hash The action id
+---@param action action The action table
+---@return boolean is_consumed True if the input was consumed
 function M:on_input(action_id, action)
 	if action_id ~= const.ACTION_TOUCH then
 		return false
@@ -93,8 +95,7 @@ function M:on_input_interrupt()
 end
 
 
----Strict swipe click area. Useful for
----restrict events outside stencil node
+---Set the click zone for the swipe, useful for restricting events outside stencil node
 ---@param zone node|string|nil Gui node
 function M:set_click_zone(zone)
 	if not zone then
@@ -107,7 +108,7 @@ end
 
 
 ---Start swipe event
----@param action action
+---@param action action The action table
 function M:_start_swipe(action)
 	self._swipe_start_time = socket.gettime()
 	self._start_pos.x = action.x

druid/extended/timer.lua

@@ -2,15 +2,16 @@ local event = require("event.event")
 local helper = require("druid.helper")
 local component = require("druid.component")
 
+---The component that handles a text to display a seconds timer
 ---@class druid.timer: druid.component
----@field on_tick event
----@field on_set_enabled event
----@field on_timer_end event
----@field node node
----@field from number
----@field target number
----@field value number
----@field is_on boolean|nil
+---@field on_tick event fun(context, value) The event triggered when the timer ticks
+---@field on_set_enabled event fun(context, is_on) The event triggered when the timer is enabled
+---@field on_timer_end event fun(context) The event triggered when the timer ends
+---@field node node The node to display the timer
+---@field from number The start time of the timer
+---@field target number The target time of the timer
+---@field value number The current value of the timer
+---@field is_on boolean|nil True if the timer is on
 local M = component.create("timer")
 
 
@@ -69,8 +70,9 @@ function M:on_layout_change()
 end
 
 
+---Set the timer to a specific value
 ---@param set_to number Value in seconds
----@return druid.timer self
+---@return druid.timer self Current timer instance
 function M:set_to(set_to)
 	self.last_value = set_to
 	gui.set_text(self.node, self:_second_string_min(set_to))
@@ -79,8 +81,9 @@ function M:set_to(set_to)
 end
 
 
+---Set the timer to a specific value
 ---@param is_on boolean|nil Timer enable state
----@return druid.timer self
+---@return druid.timer self Current timer instance
 function M:set_state(is_on)
 	self.is_on = is_on
 	self.on_set_enabled:trigger(self:get_context(), is_on)
@@ -89,9 +92,10 @@ function M:set_state(is_on)
 end
 
 
+---Set the timer interval
 ---@param from number Start time in seconds
 ---@param to number Target time in seconds
----@return druid.timer self
+---@return druid.timer self Current timer instance
 function M:set_interval(from, to)
 	self.from = from
 	self.value = from
@@ -104,6 +108,9 @@ function M:set_interval(from, to)
 end
 
 
+---@private
+---@param sec number Seconds to convert
+---@return string The formatted time string
 function M:_second_string_min(sec)
 	local mins = math.floor(sec / 60)
 	local seconds = math.floor(sec - mins * 60)