Update docs

druid/base/back_handler.lua

@@ -6,13 +6,11 @@
 -- Back Handler is recommended to put in every game window to close it
 -- or in main screen to call settings window.
 --
--- # Tech Info #
---
--- Back Handler react on release action ACTION_BACK or ACTION_BACKSPACE
---
 -- # Notes #
 --
 -- • Back Handler inheritance @{BaseComponent}, you can use all of its methods in addition to those described here.
+--
+-- • Back Handler react on release action ACTION_BACK or ACTION_BACKSPACE
 -- @usage
 -- local callback = function(self, params) ... end
 --
@@ -22,7 +20,7 @@
 -- @within BaseComponent
 -- @alias druid.back_handler
 
---- @{DruidEvent} function(self, [params]) .
+--- @{DruidEvent} Event on back handler action.
 --
 -- Trigger on input action ACTION_BACK or ACTION_BACKSPACE
 -- @usage
@@ -30,7 +28,7 @@
 -- back_handler.on_back:subscribe(callback)
 -- @tfield DruidEvent on_back @{DruidEvent}
 
---- Params to pass in the callback
+--- Custom args to pass in the callback
 -- @usage
 -- -- Replace params on runtime:
 -- back_handler.params = { ... }
@@ -45,13 +43,13 @@ local component = require("druid.component")
 local BackHandler = component.create("back_handler")
 
 
---- Component initialize function
+--- @{BackHandler} constructor
 -- @tparam BackHandler self @{BackHandler}
 -- @tparam callback callback On back button
--- @tparam[opt] any params Callback argument
+-- @tparam[opt] any custom_args Button events custom arguments
 -- @local
-function BackHandler.init(self, callback, params)
-	self.params = params
+function BackHandler.init(self, callback, custom_args)
+	self.params = custom_args
 	self.on_back = Event(callback)
 end
 

druid/base/blocker.lua

@@ -1,19 +1,15 @@
 -- Copyright (c) 2023 Maksim Tuprikov <insality@gmail.com>. This code is licensed under MIT license
 
---- Component to block input in special zone defined by GUI node.
+--- Component to consume input in special zone defined by GUI node.
 -- # Overview #
 --
--- Blocker component необходим, чтобы блокировать пользовательский ввод в определенной зоне.
--- Зона задается размером ноды, на которой находится компонент. Blocker блокирует ввод только для тех
--- элементов, которые находятся перед ним in input stack (созданы до него).
---
--- # Tech Info #
---
--- Blocker consume input if `gui.pick_node` works on it.
---
 -- # Notes #
 --
+-- Blocker consume input if `gui.pick_node` works on it.
+--
 -- • Blocker inheritance @{BaseComponent}, you can use all of its methods in addition to those described here.
+--
+-- • Blocker initial enabled state is `gui.is_enabled(node, true)`
 -- @usage
 -- local node = gui.get_node("blocker_node")
 -- local blocker = self.druid:new_blocker(node)
@@ -21,7 +17,7 @@
 -- @within BaseComponent
 -- @alias druid.blocker
 
----Trigger node
+---Blocker node
 -- @tfield node node
 
 ---
@@ -32,12 +28,12 @@ local component = require("druid.component")
 local Blocker = component.create("blocker")
 
 
---- Component initialize function
+--- @{Blocker} constructor
 -- @tparam Blocker self @{Blocker}
 -- @tparam node node Gui node
--- @local
 function Blocker.init(self, node)
 	self.node = self:get_node(node)
+	self._is_enabled = gui.is_enabled(node, true)
 end
 
 
@@ -65,11 +61,13 @@ function Blocker.on_input(self, action_id, action)
 end
 
 
---- Set enabled blocker component state
+--- Set enabled blocker component state.
+--
+-- Don't change node enabled state.
 -- @tparam Blocker self @{Blocker}
 -- @tparam bool state Enabled state
 function Blocker.set_enabled(self, state)
-	gui.set_enabled(self.node, state)
+	self._is_enabled = state
 end
 
 
@@ -77,7 +75,7 @@ end
 -- @tparam Blocker self @{Blocker}
 -- @treturn bool True, if blocker is enabled
 function Blocker.is_enabled(self)
-	return gui.is_enabled(self.node)
+	return self._is_enabled
 end
 
 

druid/base/button.lua

@@ -3,7 +3,7 @@
 --- Druid Component to handle the user click interactions: click, long click, double click, etc.
 -- # Overview #
 --
--- The most generic and useful component you can use. Set any GUI node clickable and providing different callbacks.
+-- The most generic component you can use. Set any GUI node clickable and provide different callbacks.
 --
 -- # Notes #
 --
@@ -107,11 +107,11 @@
 -- end)
 -- @tfield DruidEvent on_pressed @{DruidEvent}
 
---- Button clickable node
--- @tfield node node
+--- Button trigger node
+-- @tfield Node node
 
 ---The GUI node id from button node
--- @tfield node_id hash
+-- @tfield hash node_id
 
 --- Button animation node.
 -- In default case equals to clickable node.
@@ -274,8 +274,8 @@ end
 -- @tparam Button self @{Button}
 -- @tparam string|Node node Node name or GUI Node itself
 -- @tparam function callback On click button callback
--- @tparam[opt] table custom_args Button events custom arguments
--- @tparam[opt] string|Node anim_node Node to animate instead of trigger node
+-- @tparam[opt] any custom_args Button events custom arguments
+-- @tparam[opt] string|Node anim_node Node to animate instead of trigger node.
 function Button.init(self, node, callback, custom_args, anim_node)
 	self.druid = self:get_druid()
 	self.node = self:get_node(node)

druid/base/scroll.lua

@@ -1,12 +1,30 @@
 -- Copyright (c) 2021 Maksim Tuprikov <insality@gmail.com>. This code is licensed under MIT license
 
 --- Component to handle scroll content.
+-- # Overview #
+--
 -- Scroll consist from two nodes: scroll parent and scroll input
 -- Scroll input the user input zone, it's static
 -- Scroll parent the scroll moving part, it will change position.
 -- Setup initial scroll size by changing scroll parent size. If scroll parent
--- size will be less than scroll_input size, no scroll is available. For scroll
--- parent size should be more than input size
+-- size will be less than scroll_input size, no scroll is available.
+--
+-- # Notes #
+--
+-- • Scroll by default style have inertion and extra size for strecthing effect.
+-- It can be adjust via scroll <a href="https://insality.github.io/druid/modules/Scroll.html#Style">style settings</a>
+--
+-- • You can setup "points of interest". Scroll always will be centered on closes point of interest.
+-- It is able to create slider without inertion and points of interest on each scroll element.
+--
+-- • You can adjust scroll content size by `scroll:set_size(node_size)`.
+-- It will setup new size to _content node_
+--
+-- • You can enabled or disable inertion mode via `scroll:set_inert(state)`
+--
+-- • You can adjust extra stretch size via `scroll:set_extra_stretch_size`
+--
+-- • Multitouch is required for scroll. Scroll is correctly handling touch_id swap while dragging scroll
 -- @module Scroll
 -- @within BaseComponent
 -- @alias druid.scroll
@@ -132,10 +150,10 @@ function Scroll.on_style_change(self, style)
 end
 
 
---- Scroll constructor
+--- @{Scroll} constructor
 -- @tparam Scroll self @{Scroll}
--- @tparam node view_node GUI view scroll node
--- @tparam node content_node GUI content scroll node
+-- @tparam string|node view_node GUI view scroll node
+-- @tparam string|node content_node GUI content scroll node
 function Scroll.init(self, view_node, content_node)
 	self.druid = self:get_druid()
 

druid/base/static_grid.lua

@@ -1,7 +1,27 @@
 -- Copyright (c) 2021 Maksim Tuprikov <insality@gmail.com>. This code is licensed under MIT license
 
---- Component to handle placing components by row and columns.
--- Grid can anchor your elements, get content size and other
+--- Component to handle component's position by row and columns.
+-- # Overview #
+--
+-- # Notes #
+--
+-- • Static grid have constant node size, so it possible to calculate node positions before placement. Nodes can be placed with gaps.
+--
+-- • Static grid can shift elements on add/remove functions.
+--
+-- • On _add node_ grid will set node parent to _parent_node_
+--
+-- • You can get array of position of every element for setup points of interest in scroll component
+--
+-- • You can get size of all elements for setup size in scroll component
+--
+-- • You can bind the grid to the scroll component for auto resize scroll content size
+--
+-- • Pivot of parent_node matter for node placement
+--
+-- • Prefab node used to get node size and anchor
+--
+-- • You can point *position_function* for animations with _static_grid:set_position_function(node, pos)_ callback. Default - *gui.set_position()*
 -- @module StaticGrid
 -- @within BaseComponent
 -- @alias druid.static_grid
@@ -81,9 +101,9 @@ function StaticGrid.on_style_change(self, style)
 end
 
 
---- Component init function
+--- @{StaticGrid} constructor
 -- @tparam StaticGrid self @{StaticGrid}
--- @tparam node parent The gui node parent, where items will be placed
+-- @tparam string|Node parent The GUI Node container, where grid's items will be placed
 -- @tparam node element Element prefab. Need to get it size
 -- @tparam[opt=1] number in_row How many nodes in row can be placed
 function StaticGrid.init(self, parent, element, in_row)

druid/base/text.lua

@@ -1,8 +1,29 @@
 -- Copyright (c) 2021 Maksim Tuprikov <insality@gmail.com>. This code is licensed under MIT license
 
---- Component to handle all GUI texts.
--- Druid Text adjust itself for text node size
--- Text will never will be outside of his text size (even multiline)
+--- Component to wrap over GUI Text nodes.
+-- # Overview #
+--
+-- Druid Text provide different adjust modes. Text will be scaled down to fit into Text Node area size.
+--
+-- # Notes #
+--
+-- • Text pivot can be changed with `text:set_pivot`. The anchoring will be inside text node area size.
+--
+-- • There is several text adjust types. Default DOWNSCALE. You can change the default adjust type in the Text style. See all adjust types in example here.
+--
+-- - const.TEXT_ADJUST.DOWNSCALE  - Change text's scale to fit into the text node size
+--
+-- - const.TEXT_ADJUST.TRIM - Trim the text with postfix (default - "...", override in styles) to fit in the text node size
+--
+-- - const.TEXT_ADJUST.NO_ADJUST - No any adjust, like default Defold Text Node
+--
+-- - const.TEXT_ADJUST.DOWNSCALE_LIMITED - Change text's scale list downscale, but there is limit for text's scale.
+-- Set minimal scale with `text:set_minimal_scale()` function.
+--
+-- - const.TEXT_ADJUST.SCROLL - Change text's pivot to imitate scrolling in the text box. Use with stencil node for better effect.
+--
+-- - const.TEXT_ADJUST.SCALE_THEN_SCROLL - Combine two modes: first limited downscale, then scroll
+--
 -- @module Text
 -- @within BaseComponent
 -- @alias druid.text
@@ -188,11 +209,11 @@ function Text.on_style_change(self, style)
 end
 
 
---- Component init function
+--- @{Text} constructor
 -- @tparam Text self @{Text}
--- @tparam node node Gui text node
+-- @tparam string|node node Node name or GUI Text Node itself
 -- @tparam[opt] string value Initial text. Default value is node text from GUI scene.
--- @tparam[opt=0] int adjust_type Adjust type for text. By default is DOWNSCALE. Look const.TEXT_ADJUST for reference
+-- @tparam[opt=downscale] string adjust_type Adjust type for text. By default is DOWNSCALE. Look const.TEXT_ADJUST for reference
 function Text.init(self, node, value, adjust_type)
 	self.node = self:get_node(node)
 	self.pos = gui.get_position(self.node)