Update readme and docs

README.md

@@ -7,11 +7,7 @@
 [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/insality/druid/ci-workflow.yml?branch=master)](https://github.com/Insality/druid/actions)
 [![codecov](https://codecov.io/gh/Insality/druid/branch/master/graph/badge.svg)](https://codecov.io/gh/Insality/druid)
 
-**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.
+**Druid** - most powerful Defold component UI framework. Use basic and extended **Druid** components or make your own game-specific components with ease to make stunning and customizable GUI in your games.
-
-
-## Overview
-
 
 
 ## Setup
@@ -26,89 +22,52 @@ You can use the **Druid** extension in your own project by adding this project a
 Here is a list of [all releases](https://github.com/Insality/druid/releases).
 
 ### Input Bindings
-Druid uses `/builtins/input/all.input_binding` input bindins. For advanced setup see the Input Binding section in Advanced Setup.
+**Druid** uses `/builtins/input/all.input_binding` input bindings. For custom input bindings see the Input Binding section in **_[Advanced Setup](docs_md/advanced-setup.md)_**.
+
+### Advanced Setup
+In case you want to adjust **Druid** to your needs, you can use **_[Advanced Setup](docs_md/advanced-setup.md)_** section.
 
 
 ## Usage
 
-Here only basic usage.
+### Basic usage
-How to read this doc.
-Annotations.
-Example of advanced usage - different doc.
-Example of custom components - different doc.
 
-## Components
+To use **Druid**, first you should create a **Druid** instance to spawn components and add Druids main functions: *update*, *final*, *on_message* and *on_input*.
 
-Here is full **Druid** components list:
+All **Druid** components take node name string as argument. In in some cases you don't have the node name you can pass the `gui.get_node()` instead.
-
-### Basic Components
-
-| Name | Description | Example | <div style="width:200px">Preview</div> |
-|------|-------------|---------|---------|
-| **[Button](https://insality.github.io/druid/modules/Button.html)** | Basic input component. Handles all types of interactions: click, long click, hold click, double click, etc | [Button Example](https://insality.github.io/druid/druid/?example=general_buttons) | <img src="media/preview/button.gif" width="200" height="100"> |
-| **[Text](https://insality.github.io/druid/modules/Text.html)** | Wrap on GUI text node, handle different text size adjusting, providing additional text API | [Text Example](https://insality.github.io/druid/druid/?example=texts_general) | <img src="media/preview/text.gif" width="200" height="100"> |
-| **[Scroll](https://insality.github.io/druid/modules/Scroll.html)** | Scroll component | [Scroll Example](https://insality.github.io/druid/druid/?example=general_scroll) | <img src="media/preview/scroll.gif" width="200" height="100"> |
-| **[Blocker](https://insality.github.io/druid/modules/Blocker.html)** | Block user input in node zone area | ❌ | |
-| **[Back Handler](https://insality.github.io/druid/modules/BackHandler.html)** | Handle back button (Android back button, backspace key) | ❌ | |
-| **[Static Grid](https://insality.github.io/druid/modules/StaticGrid.html)** | Component to manage node positions with equal sizes | [Static Gid Example](https://insality.github.io/druid/druid/?example=general_grid) | <img src="media/preview/static_grid.gif" width="200" height="100"> |
-| **[Hover](https://insality.github.io/druid/modules/Hover.html)** | Handle hover node state on node | ❌ | <img src="media/preview/hover.gif" width="200" height="100"> |
-| **[Swipe](https://insality.github.io/druid/modules/Swipe.html)** | Handle swipe gestures on node | [Swipe Example](https://insality.github.io/druid/druid/?example=general_swipe) | <img src="media/preview/swipe.gif" width="200" height="100"> |
-| **[Drag](https://insality.github.io/druid/modules/Drag.html)** | Handle drag input on node | [Drag Example](https://insality.github.io/druid/druid/?example=general_drag) | <img src="media/preview/drag.gif" width="200" height="100"> |
-
-
-### Extended components
-> Extended components before usage should be registered in **Druid** with `druid.register()` function.
-
-| Name | Description | Example | <div style="width:200px">Preview</div> |
-|------|-------------|---------|---------|
-| **[Checkbox](https://insality.github.io/druid/modules/Checkbox.html)** | Checkbox component | [Checkbox Example](https://insality.github.io/druid/druid/?example=general_checkboxes) | <img src="media/preview/checkbox.gif" width="200" height="100"> |
-| **[Checkbox group](https://insality.github.io/druid/modules/CheckboxGroup.html)** | Several checkboxes in one group | [Checkbox group Example](https://insality.github.io/druid/druid/?example=general_checkboxes) | <img src="media/preview/checkbox_group.gif" width="200" height="100"> |
-| **[Radio group](https://insality.github.io/druid/modules/RadioGroup.html)** | Several checkboxes in one group with a single choice | [Radio Group Example](https://insality.github.io/druid/druid/?example=general_checkboxes) | <img src="media/preview/radio_group.gif" width="200" height="100"> |
-| **[Dynamic Grid](https://insality.github.io/druid/modules/DynamicGrid.html)** | Component to manage node positions with different sizes. Only in one row or column | [Dynamic Grid Example](https://insality.github.io/druid/druid/?example=general_grid) | <img src="media/preview/dynamic_grid.gif" width="200" height="100"> |
-| **[Data List](https://insality.github.io/druid/modules/DataList.html)** | Component to manage data for huge datasets in scroll | [Data List Example](https://insality.github.io/druid/druid/?example=general_data_list) | <img src="media/preview/data_list.gif" width="200" height="100"> |
-| **[Input](https://insality.github.io/druid/modules/Input.html)** | User text input component | [Input Example](https://insality.github.io/druid/druid/?example=general_input) | <img src="media/preview/input.gif" width="200" height="100"> |
-| **[Lang text](https://insality.github.io/druid/modules/LangText.html)** | Wrap on Text component to handle localization | ❌ | <img src="media/preview/lang_text.gif" width="200" height="100"> |
-| **[Progress](https://insality.github.io/druid/modules/Progress.html)** | Progress bar component | [Progress Example](https://insality.github.io/druid/druid/?example=general_progress_bar) | <img src="media/preview/progress.gif" width="200" height="100"> |
-| **[Slider](https://insality.github.io/druid/modules/Slider.html)** | Slider component | [Slider Example]() | <img src="media/preview/slider.gif" width="200" height="100"> |
-| **[Timer](https://insality.github.io/druid/modules/Timer.html)** | Handle timers on GUI text node | ❌ | <img src="media/preview/timer.gif" width="200" height="100"> |
-| **[Hotkey](https://insality.github.io/druid/modules/Hotkey.html)** | Handle keyboard hotkeys with key modificators | [Hotkey Example](https://insality.github.io/druid/druid/?example=general_hokey) | <img src="media/preview/hotkey.gif" width="200" height="100"> |
-| **[Layout](https://insality.github.io/druid/modules/Layout.html)** | Handle node size depends on layout mode and screen aspect ratio | [Layout Example](https://insality.github.io/druid/druid/?example=general_layout) | <img src="media/preview/layout.gif" width="200" height="100"> |
-
-For a complete overview, see: **_[components.md](docs_md/01-components.md)_**.
-
-
-## Basic usage
-
-To use **Druid**, first you should create a Druid instance to spawn components and add Druids main engine functions: *update*, *final*, *on_message* and *on_input*.
-
-All **Druid** components take node name string as arguments, don't do `gui.get_node()` before.
 
 All **Druid** and component methods are called with `:` like `self.druid:new_button()`.
 
 ```lua
 local druid = require("druid.druid")
 
-local function button_callback(self)
+-- All component callbacks pass "self" as first argument
-    print("Button was clicked!")
+-- This self is a context data passed in `druid.new(context)`
+local function on_button_callback(self)
+    print("The button clicked!")
 end
 
 function init(self)
     self.druid = druid.new(self)
-    self.druid:new_button("button_node_name", button_callback)
+    self.button = self.druid:new_button("button_node_name", on_button_callback)
 end
 
+-- Final is a required function for a correct Druid workflow
 function final(self)
     self.druid:final()
 end
 
+-- The update used in progress bar, scroll and timer basic components
 function update(self, dt)
     self.druid:update(dt)
 end
 
+-- The on_message used for specific Druid events, like language change or layout change
 function on_message(self, message_id, message, sender)
     self.druid:on_message(message_id, message, sender)
 end
 
+-- The on_input used in almost all Druid components
 function on_input(self, action_id, action)
     return self.druid:on_input(action_id, action)
 end
@@ -117,9 +76,89 @@ end
 
 For all **Druid** instance functions, [see here](https://insality.github.io/druid/modules/DruidInstance.html).
 
+
+### API Documentation
+
+**Druid** has a lot of components and functions. To make it easier to use, **Druid** has a full API documentation with examples and annotations.
+
+Start read the API documentation [here](hhttps://insality.github.io/druid/modules/Druid.html).
+
+### EmmyLua Annotations [optional]
+
+[EmmyLua](https://emmylua.github.io/annotation.html) - annotations for Lua. It's a great tool for Lua code autocompletion in editors like [VSCode](https://github.com/EmmyLua/VSCode-EmmyLua), [IntelliJ IDEA](https://github.com/EmmyLua/IntelliJ-EmmyLua).
+
+Since the dependencies can't be processed by external editors, for use generated EmmyLua annotations you should copy the _druid/annotations.lua_ to your project.
+
+For EmmyLua it will be enough. Remember you can _restart emmylua server_ for refresh the changes, if something goes wrong.
+
+After the annotations is processed, you should point the type of Druid in requires:
+```lua
+---@type druid
+local druid = require("druid.druid")
+
+-- Now the autocomplete is working
+```
+
+<img src="media/emmy_lua_preview.png" width="700">
+
+### Advanced Usage
+
+If you looking for more advanced usage, see the [Advanced Usage](docs_md/advanced-usage.md) section.
+
+
+### Create custom components
+
+If you want to create your own components, see the [Create Custom Components](docs_md/create-custom-components.md) section.
+
+The custom components is the most powerful feature of **Druid**. You can create your own components with ease and use it in your game.
+
+
+## Druid Components
+
+Here is full **Druid** components list.
+
+### Basic Components
+
+> Basic components always included in the build and available for use.
+
+| Name | Description | Example | <div style="width:200px">Preview</div> |
+|------|-------------|---------|---------|
+| **[Button](https://insality.github.io/druid/modules/Button.html)** | Logic over GUI Node. Handle the user click interactions: click, long click, double click, etc. | [Button Example](https://insality.github.io/druid/druid/?example=general_buttons) | <img src="media/preview/button.gif" width="200" height="100"> |
+| **[Text](https://insality.github.io/druid/modules/Text.html)** | Logic over GUI Text. By default Text component fit the text inside text node size area with different adjust modes. | [Text Example](https://insality.github.io/druid/druid/?example=texts_general) | <img src="media/preview/text.gif" width="200" height="100"> |
+| **[Scroll](https://insality.github.io/druid/modules/Scroll.html)** | Logic over two GUI Nodes: input and content. Provides basic behaviour for scrollable content. | [Scroll Example](https://insality.github.io/druid/druid/?example=general_scroll) | <img src="media/preview/scroll.gif" width="200" height="100"> |
+| **[Blocker](https://insality.github.io/druid/modules/Blocker.html)** | Logic over GUI Node. Don't pass any user input below node area size. | ❌ | |
+| **[Back Handler](https://insality.github.io/druid/modules/BackHandler.html)** | Call callback on user "Back" action. It's a Android back button or keyboard backspace key | ❌ | |
+| **[Static Grid](https://insality.github.io/druid/modules/StaticGrid.html)** | Logic over GUI Node. Component to manage node positions with all equal node sizes. | [Static Gid Example](https://insality.github.io/druid/druid/?example=general_grid) | <img src="media/preview/static_grid.gif" width="200" height="100"> |
+| **[Hover](https://insality.github.io/druid/modules/Hover.html)** | Logic over GUI Node. Handle hover action over node. For both: mobile touch and mouse cursor. | ❌ | <img src="media/preview/hover.gif" width="200" height="100"> |
+| **[Swipe](https://insality.github.io/druid/modules/Swipe.html)** | Logic over GUI Node. Handle swipe gestures over node. | [Swipe Example](https://insality.github.io/druid/druid/?example=general_swipe) | <img src="media/preview/swipe.gif" width="200" height="100"> |
+| **[Drag](https://insality.github.io/druid/modules/Drag.html)** | Logic over GUI Node. Handle drag input actions. Can be useful to make on screen controlls. | [Drag Example](https://insality.github.io/druid/druid/?example=general_drag) | <img src="media/preview/drag.gif" width="200" height="100"> |
+
+
+### Extended components
+
+> Extended components before usage should be registered in **Druid** with `druid.register()` function.
+
+| Name | Description | Example | <div style="width:200px">Preview</div> |
+|------|-------------|---------|---------|
+| **[Checkbox](https://insality.github.io/druid/modules/Checkbox.html)** | Switch node state on click event. | [Checkbox Example](https://insality.github.io/druid/druid/?example=general_checkboxes) | <img src="media/preview/checkbox.gif" width="200" height="100"> |
+| **[Checkbox group](https://insality.github.io/druid/modules/CheckboxGroup.html)** | Group of checkbox components. | [Checkbox group Example](https://insality.github.io/druid/druid/?example=general_checkboxes) | <img src="media/preview/checkbox_group.gif" width="200" height="100"> |
+| **[Radio group](https://insality.github.io/druid/modules/RadioGroup.html)** | Like checkbox group but with single choise only. | [Radio Group Example](https://insality.github.io/druid/druid/?example=general_checkboxes) | <img src="media/preview/radio_group.gif" width="200" height="100"> |
+| **[Dynamic Grid](https://insality.github.io/druid/modules/DynamicGrid.html)** | Logic over GUI Node. Component to manage node positions with all different node sizes. Only one direction: horizontal or vertical. | [Dynamic Grid Example](https://insality.github.io/druid/druid/?example=general_grid) | <img src="media/preview/dynamic_grid.gif" width="200" height="100"> |
+| **[Data List](https://insality.github.io/druid/modules/DataList.html)** | Logic over Scroll and Grid components. Create only visible GUI nodes or components to make "infinity" scroll befaviour | [Data List Example](https://insality.github.io/druid/druid/?example=general_data_list) | <img src="media/preview/data_list.gif" width="200" height="100"> |
+| **[Input](https://insality.github.io/druid/modules/Input.html)** | Logic over GUI Node and GUI Text (or Text component). Provides basic user text input. | [Input Example](https://insality.github.io/druid/druid/?example=general_input) | <img src="media/preview/input.gif" width="200" height="100"> |
+| **[Lang text](https://insality.github.io/druid/modules/LangText.html)** | Logic over Text component to handle localization. Can be translated in real-time with `druid.on_language_change` | ❌ | <img src="media/preview/lang_text.gif" width="200" height="100"> |
+| **[Progress](https://insality.github.io/druid/modules/Progress.html)** | Logic over GUI Node. Handle node size and scale to handle progress node size. | [Progress Example](https://insality.github.io/druid/druid/?example=general_progress_bar) | <img src="media/preview/progress.gif" width="200" height="100"> |
+| **[Slider](https://insality.github.io/druid/modules/Slider.html)** | Logic over GUI Node. Handle draggable node with position restrictions. | [Slider Example]() | <img src="media/preview/slider.gif" width="200" height="100"> |
+| **[Timer](https://insality.github.io/druid/modules/Timer.html)** | Logic over GUI Text. Handle basic timer functions. | ❌ | <img src="media/preview/timer.gif" width="200" height="100"> |
+| **[Hotkey](https://insality.github.io/druid/modules/Hotkey.html)** | Allow to set callbacks for keyboard hotkeys with key modificators. | [Hotkey Example](https://insality.github.io/druid/druid/?example=general_hokey) | <img src="media/preview/hotkey.gif" width="200" height="100"> |
+| **[Layout](https://insality.github.io/druid/modules/Layout.html)** | Logic over GUI Node. Handle node size depends on layout mode and screen aspect ratio. Contains helpers to build more complex UI layout. | [Layout Example](https://insality.github.io/druid/druid/?example=general_layout) | <img src="media/preview/layout.gif" width="200" height="100"> |
+
+For a complete overview, see: **_[components.md](docs_md/01-components.md)_**.
+
+
 ## Druid Events
 
-Any **Druid** components as callbacks use [Druid Events](https://insality.github.io/druid/modules/DruidEvent.html). In component API ([button example](https://insality.github.io/druid/modules/Button.html#on_click)) pointed list of component events. You can manually subscribe to those events with the following API:
+Any **Druid** components as callbacks use [Druid Events](https://insality.github.io/druid/modules/DruidEvent.html). In component API ([button example](https://insality.github.io/druid/modules/Button.html#on_click)) pointed list of component events. You can manually subscribe to these events with the following API:
 
 - **event:subscribe**(callback)
 
@@ -129,57 +168,29 @@ Any **Druid** components as callbacks use [Druid Events](https://insality.github
 
 You can subscribe several callbacks to a single event.
 
-## Druid Lifecycle
-
-Here is full Druid lifecycle setup for your ***.gui_script** file:
-```lua
-local druid = require("druid.druid")
-
-function init(self)
-    self.druid = druid.new(self)
-end
-
-function final(self)
-    self.druid:final()
-end
-
-function update(self, dt)
-    self.druid:update(dt)
-end
-
-function on_input(self, action_id, action)
-    return self.druid:on_input(action_id, action)
-end
-
-function on_message(self, message_id, message, sender)
-    self.druid:on_message(message_id, message, sender)
-end
-```
-
-- *final* is a **required** function for a correct Druid lifecycle
-- *on_input* is used in almost all Druid components
-- *update* in used in progress bar, scroll and timer base components
-- *on_message* is used for specific Druid events, like language change or layout change
-
-It is recommended to fully integrate all **Druid** lifecycles functions.
-
-
 ## Details
 
-- Druid input goes as stack. Last created button will checked first. So create your GUI from back
+- **Druid** input goes as stack. Last created button will be checked first. Create your input GUI component from back to front.
-- Don't forget about `return` in `on_input`: `return self.druid:on_input()`. It is needed if you have more than 1 acquire inputs (several Druid, other input system, etc)
+- Don't forget about `return` in `on_input`: `return self.druid:on_input()`. It is required if you have more than 1 acquire inputs (several Druid, other input system, etc)
-- By default, Druid will automatically _acquire_input_focus_. So you don't need do it manually. But only if you have components which require _on_input_
+- Druid automatically call _acquire_input_focus_ if you have input components. So you don't required to call it manually.
-- If you want to delete a node which has a Druid component, don't forget to remove it via `druid:remove(component)`
+- If you want to delete a **Druid** component node, don't forget to remove it via `druid:remove(component)`
 
 [See full FAQ here](docs_md/FAQ.md)
 
 
 ## Examples
 
-See the [**example folder**](https://github.com/Insality/druid/tree/develop/example) for examples of how to use **Druid**
+### HTML5 Live Examples
 
 Try the [**HTML5 version**](https://insality.github.io/druid/druid/) of the **Druid** example app
 
+Each example page has a link to the example code directly, so it will help you to faster understand how to use **Druid**
+
+
+### Code examples
+
+See the [**example folder**](https://github.com/Insality/druid/tree/develop/example) for examples of how to use **Druid**
+
 
 ## Documentation
 

deployer_build_stats.csv

@@ -9,3 +9,4 @@ date,sha,version,build_size,build_time,platform,mode,is_cache_using,commits_coun
 2022-08-29T18:46:47Z,13003e472169cbd261e703eca7b133adf64a24f7,0.9.592,2316,40,js-web,release,true,592
 2022-09-09T17:55:42Z,072507cc9e715541bdee7636d2e5eeeb3c22a57d,0.10.603,2340,43,js-web,release,true,603
 2022-09-09T18:00:07Z,072507cc9e715541bdee7636d2e5eeeb3c22a57d,0.10.603,2340,5,js-web,release,true,603
+2023-07-05T20:19:22Z,d0062c2a78e618871ebb4c8ee66b1509b763f069,0.10.671,3292,12,x86_64-linux,headless,true,671

docs_md/advanced-setup.md

@@ -1,5 +1,10 @@
+# Advanced Druid setup
+
+
 ## Input bindings
 
+As default input bindings **Druid** uses the `/builtins/input/all.input_binding`.
+
 **Druid** requires the following input bindings:
 
 - Mouse trigger - `Button 1` -> `touch` _For basic input components_
@@ -14,6 +19,7 @@
 ![](media/input_binding_2.png)
 ![](media/input_binding_1.png)
 
+
 ## Change key bindings [optional]
 If you have to use your own key bindings (and key name), you can change it in your *game.project* file.
 
@@ -59,6 +65,8 @@ no_auto_template = 1
 ## Stencil check [optional]
 
 When creating input components inside stencil nodes, **Druid** automatically setup `component:set_click_zone()` on _late_init_ component step to restrict input clicks outside this stencil zone.
+For example: button inside scroll stencil nodes.
+
 To disable this feature add next field in your _game.project_ file
 ```
 [druid]
@@ -66,7 +74,7 @@ no_stencil_check = 1
 ```
 
 
-## Code [optional]
+## Code bindings [optional]
 
 Adjust **Druid** settings, if needed:
 ```lua
@@ -74,21 +82,30 @@ local druid = require("druid.druid")
 
 -- Used for button component and custom components
 -- Callback should play sound by name: function(sound_id) ... end
-druid.set_sound_function(callback)
+druid.set_sound_function(function(sound_id)
+    -- sound_system.play(sound_id)
+end)
 
 -- Used for lang_text component
 -- Callback should return localized string by locale id: function(locale_id) ... end
-druid.set_text_function(callback)
+druid.set_text_function(function(locale_id)
+	-- return lang.get(locale_id)
+end)
 
 -- Used for change default Druid style
 druid.set_default_style(your_style)
 
 -- Call this function on language changing in the game,
 -- to retranslate all lang_text components:
+local function on_language_change()
     druid.on_language_change()
+end
 
 -- Call this function inside window.set_listener
 -- to catch game focus lost/gained callbacks:
 -- window.set_listener(function(self, event, data) druid.on_window_callback(event, data) end))
+local function on_window_callback(self, event, data)
     druid.on_window_callback(event)
+end
+window.set_listener(on_window_callback)
 ```

druid/annotations.lua

@@ -20,7 +20,7 @@ function druid.on_language_change() end
 function druid.on_window_callback(event) end
 
 --- Register a new external Druid component.
---- You can register your own components by creating them with 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.
+--- 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.
 ---@param name string module name
 ---@param module table lua table with component
 function druid.register(name, module) end
@@ -125,7 +125,7 @@ function druid__base_component.component:set_input_enabled(self, state) end
 function druid__base_component.component:set_input_priority(self, value, is_temporary) end
 
 --- Set current component nodes
---- Used if your component nodes was cloned with `gui.clone_tree`
+--- Use if your component nodes was cloned with `gui.clone_tree` and you got the node tree.
 ---@param self druid.base_component @{BaseComponent}
 ---@param nodes table BaseComponent nodes table
 ---@return druid.base_component @{BaseComponent}
@@ -162,31 +162,28 @@ function druid__blocker.set_enabled(self, state) end
 
 
 ---@class druid.button : druid.base_component
----@field anim_node node Animation node
+---@field anim_node node Button animation node.
----@field click_zone node Restriction zone
+---@field click_zone node Additional button click area, defined by another GUI Node
----@field hash node_id The hash of trigger node
+---@field hash node_id The GUI node id from button node
----@field hover druid.hover Druid hover logic component
+---@field hover druid.hover @{Hover}: Button Hover component
----@field node node Trigger node
+---@field node node Button clickable node
----@field on_click druid.event On release button callback(self, params, button_instance)
+---@field on_click druid.event @{DruidEvent}: Event on successful release action over button.
----@field on_click_outside druid.event On click outside of button(self, params, button_instance)
+---@field on_click_outside druid.event @{DruidEvent}: Event calls if click event was outside of button.
----@field on_double_click druid.event On double tap button callback(self, params, button_instance, click_amount)
+---@field on_double_click druid.event @{DruidEvent}: Event on double tap action over button.
----@field on_hold_callback druid.event On button hold before long_click callback(self, params, button_instance, time)
+---@field on_hold_callback druid.event @{DruidEvent}: Event calls every frame before on_long_click event.
----@field on_long_click druid.event On long tap button callback(self, params, button_instance, time)
+---@field on_long_click druid.event @{DruidEvent}: Event on long tap action over button.
----@field on_pressed druid.event On pressed button callback(self, params, button_instance)
+---@field on_pressed druid.event @{DruidEvent}: Event triggered if button was pressed by user.
----@field on_repeated_click druid.event On repeated action button callback(self, params, button_instance, click_amount)
+---@field on_repeated_click druid.event @{DruidEvent}: Event on repeated action over button.
----@field params any Params to click callbacks
+---@field params any Custom args for any Button event.
----@field pos vector3 Initial pos of anim_node
----@field start_pos vector3 Initial pos of anim_node
----@field start_scale vector3 Initial scale of anim_node
 ---@field style druid.button.style Component style params.
 local druid__button = {}
 
---- Get key-code to trigger this button
+--- Get current key name to trigger this button.
 ---@param self druid.button
----@return hash The action_id of the key
+---@return hash The action_id of the input key
 function druid__button.get_key_trigger(self) end
 
---- Component init function
+--- Button component constructor
 ---@param self druid.button @{Button}
 ---@param node node Gui node
 ---@param callback function Button callback
@@ -194,9 +191,9 @@ function druid__button.get_key_trigger(self) end
 ---@param anim_node node Button anim node (node, if not provided)
 function druid__button.init(self, node, callback, params, anim_node) end
 
---- Return button enabled state
+--- Get button enabled state.
 ---@param self druid.button @{Button}
----@return bool True, if button is enabled
+---@return bool True, if button is enabled now, False overwise
 function druid__button.is_enabled(self) end
 
 --- Set function for additional check for button click availability
@@ -206,29 +203,30 @@ function druid__button.is_enabled(self) end
 ---@return druid.button Current button instance
 function druid__button.set_check_function(self, check_function, failure_callback) end
 
---- Strict button click area.
+--- Set additional button click area.
---- Useful for  no click events outside stencil node
+--- Useful to restrict click outside out stencil node or scrollable content.  This functions calls automatically if you don't disable it in game.project: druid.no_stencil_check
 ---@param self druid.button @{Button}
 ---@param zone node Gui node
 ---@return druid.button Current button instance
 function druid__button.set_click_zone(self, zone) end
 
---- Set enabled button component state
+--- Set button enabled state.
+--- The style.on_set_enabled will be triggered.  Disabled button is not clickable.
 ---@param self druid.button @{Button}
 ---@param state bool Enabled state
 ---@return druid.button Current button instance
 function druid__button.set_enabled(self, state) end
 
---- Set buttom click mode to call itself inside html5 callback in user interaction event  It required to do protected stuff like copy/paste text, show html keyboard, etc  The HTML5 button don't call any events except on_click
+--- Set buttom click mode to call itself inside html5 callback in user interaction event  It required to do protected stuff like copy/paste text, show html keyboard, etc  The HTML5 button doesn't call any events except on_click event
 ---@protected
 ---@param self druid.button
 ---@param is_html_mode boolean If true - button will be called inside html5 callback
 ---@return druid.button Current button instance
 function druid__button.set_html5_user_interaction(self, is_html_mode) end
 
---- Set key-code to trigger this button
+--- Set key name to trigger this button by keyboard.
 ---@param self druid.button @{Button}
----@param key hash The action_id of the key
+---@param key hash The action_id of the input key
 ---@return druid.button Current button instance
 function druid__button.set_key_trigger(self, key) end
 
@@ -647,7 +645,7 @@ function druid__input.get_text(self) end
 
 --- Component init function
 ---@param self druid.input @{Input}
----@param click_node node Button node to enabled input component
+---@param click_node node Node to enabled input component
 ---@param text_node node|druid.text Text node what will be changed on user input. You can pass text component instead of text node name @{Text}
 ---@param keyboard_type number Gui keyboard type for input field
 function druid__input.init(self, click_node, text_node, keyboard_type) end
@@ -942,6 +940,31 @@ function druid__rich_input.set_placeholder(self, placeholder_text) end
 ---@field component field The component druid instance
 local druid__rich_text = {}
 
+--- Clear all created words.
+function druid__rich_text.clean() end
+
+--- Get all current words.
+---@return table Words
+function druid__rich_text.get_words() end
+
+--- Rich Text component constructor
+---@param self druid.rich_text @{RichText}
+---@param template string The Rich Text template name
+---@param nodes table The node table, if prefab was copied by gui.clone_tree()
+function druid__rich_text.init(self, template, nodes) end
+
+--- Set text for Rich Text
+---@param self druid.rich_text @{RichText}
+---@param text string The text to set
+---@return table words
+---@return table line_metrics
+function druid__rich_text.set_text(self, text) end
+
+--- Get all words, which has a passed tag
+---@param tag string
+---@return table Words
+function druid__rich_text.tagged(tag) end
+
 
 ---@class druid.scroll : druid.base_component
 ---@field available_pos vector4 Available position for content node: (min_x, max_y, max_x, min_y)
@@ -1578,7 +1601,7 @@ function druid_instance.on_input(self, action_id, action) end
 ---@param sender hash Sender from on_message
 function druid_instance.on_message(self, message_id, message, sender) end
 
---- Remove component from Druid instance.
+--- Remove created component from Druid instance.
 --- Component `on_remove` function will be invoked, if exist.
 ---@param self druid_instance
 ---@param component Component Component instance

druid/base/button.lua

@@ -1,56 +1,131 @@
 -- Copyright (c) 2021 Maksim Tuprikov <insality@gmail.com>. This code is licensed under MIT license
 
---- Component to handle basic GUI button
+--- 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.
+--
+-- # Notes #
+--
+-- • The click callback will not trigger if between pressed and released state cursor was outside of node zone
+--
+-- • If button have double click event subscriber and it is triggered, usual callback will be not triggered
+--
+-- • Button can have key trigger to use then by key: `button:set_key_trigger`
+--
+-- • Animation node can be used for example to animate small icon on big panel. Node name of trigger zone will be `big panel` and animation node will be `small icon`
+--
+-- @usage
+-- local function on_button_click(self, args, button)
+--     print("Button has clicked with params: " .. args)
+--     print("Also the button component is passed in callback params")
+-- end
+--
+-- local custom_args = "Any variable to pass inside callback"
+-- local button = self.druid:new_button("button_name", on_button_click, custom_args)
+--
 -- @module Button
 -- @within BaseComponent
 -- @alias druid.button
 
---- On release button callback(self, params, button_instance)
+
+--- @{DruidEvent}: Event on successful release action over button.
+-- @usage
+-- -- Custom args passed in Button constructor
+-- button.on_click:subscribe(function(self, custom_args, button_instance)
+--     print("On button click!")
+-- end)
 -- @tfield DruidEvent on_click @{DruidEvent}
 
---- On repeated action button callback(self, params, button_instance, click_amount)
+
+--- @{DruidEvent}: Event on repeated action over button.
+--
+-- This callback will be triggered if user hold the button. The repeat rate pick from `input.repeat_interval` in game.project
+-- @usage
+-- -- Custom args passed in Button constructor
+-- button.on_repeated_click:subscribe(function(self, custom_args, button_instance, click_count)
+--     print("On repeated Button click!")
+-- end)
 -- @tfield DruidEvent on_repeated_click @{DruidEvent}
 
----On long tap button callback(self, params, button_instance, time)
+
+--- @{DruidEvent}: Event on long tap action over button.
+--
+-- This callback will be triggered if user pressed the button and hold the some amount of time.
+-- The amount of time picked from button style param: LONGTAP_TIME
+-- @usage
+-- -- Custom args passed in Button constructor
+-- button.on_long_click:subscribe(function(self, custom_args, button_instance, hold_time)
+--     print("On long Button click!")
+-- end)
 -- @tfield DruidEvent on_long_click @{DruidEvent}
 
----On double tap button callback(self, params, button_instance, click_amount)
+
+--- @{DruidEvent}: Event on double tap action over button.
+--
+-- If secondary click was too fast after previous one, the double
+-- click will be called instead usual click (if on_double_click subscriber exists)
+-- @usage
+-- -- Custom args passed in Button constructor
+-- button.on_double_click:subscribe(function(self, custom_args, button_instance, click_amount)
+--     print("On double Button click!")
+-- end)
 -- @tfield DruidEvent on_double_click @{DruidEvent}
 
----On button hold before long_click callback(self, params, button_instance, time)
+
+--- @{DruidEvent}: Event calls every frame before on_long_click event.
+--
+-- If long_click subscriber exists, the on_hold_callback will be called before long_click trigger.
+--
+-- Usecase: Animate button progress of long tap
+-- @usage
+-- -- Custom args passed in Button constructor
+-- button.on_double_click:subscribe(function(self, custom_args, button_instance, time)
+--     print("On hold Button callback!")
+-- end)
 -- @tfield DruidEvent on_hold_callback @{DruidEvent}
 
----On click outside of button(self, params, button_instance)
+
+--- @{DruidEvent}: Event calls if click event was outside of button.
+--
+-- This event will be triggered for each button what was not clicked on user click action
+--
+-- Usecase: Hide the popup when click outside
+-- @usage
+-- -- Custom args passed in Button constructor
+-- button.on_click_outside:subscribe(function(self, custom_args, button_instance)
+--     print("On click Button outside!")
+-- end)
 -- @tfield DruidEvent on_click_outside @{DruidEvent}
 
----On pressed button callback(self, params, button_instance)
+
+--- @{DruidEvent}: Event triggered if button was pressed by user.
+-- @usage
+-- -- Custom args passed in Button constructor
+-- button.on_pressed:subscribe(function(self, custom_args, button_instance)
+--     print("On Button pressed!")
+-- end)
 -- @tfield DruidEvent on_pressed @{DruidEvent}
 
----Trigger node
+--- Button clickable node
 -- @tfield node node
 
----The hash of trigger node
+---The GUI node id from button node
 -- @tfield node_id hash
 
----Animation node
+--- Button animation node.
+-- In default case equals to clickable node.
+--
+-- Usecase: You have the big clickable panel, but want to animate only one small icon on it.
 -- @tfield[opt=node] node anim_node
 
----Initial scale of anim_node
+---Custom args for any Button event. Setup in Button constructor
--- @tfield vector3 start_scale
-
----Initial pos of anim_node
--- @tfield vector3 start_pos
-
----Initial pos of anim_node
--- @tfield vector3 pos
-
----Params to click callbacks
 -- @tfield any params
 
----Druid hover logic component
+--- @{Hover}: Button Hover component
 -- @tfield Hover hover @{Hover}
 
----Restriction zone
+--- Additional button click area, defined by another GUI Node
 -- @tfield[opt] node click_zone
 
 ---
@@ -195,7 +270,7 @@ function Button.on_style_change(self, style)
 end
 
 
---- Component init function
+--- Button component constructor
 -- @tparam Button self @{Button}
 -- @tparam node node Gui node
 -- @tparam function callback Button callback
@@ -357,10 +432,15 @@ function Button.on_message_input(self, node_id, message)
 end
 
 
---- Set enabled button component state
+--- Set button enabled state.
+-- The style.on_set_enabled will be triggered.
+-- Disabled button is not clickable.
 -- @tparam Button self @{Button}
 -- @tparam bool state Enabled state
 -- @treturn Button Current button instance
+-- @usage
+-- button:set_enabled(false)
+-- button:set_enabled(true)
 function Button.set_enabled(self, state)
 	self.disabled = not state
 	self.hover:set_enabled(state)
@@ -370,19 +450,25 @@ function Button.set_enabled(self, state)
 end
 
 
---- Return button enabled state
+--- Get button enabled state.
 -- @tparam Button self @{Button}
--- @treturn bool True, if button is enabled
+-- @treturn bool True, if button is enabled now, False overwise
+-- @usage
+-- local is_enabled = button:is_enabled()
 function Button.is_enabled(self)
 	return not self.disabled
 end
 
 
---- Strict button click area. Useful for
+--- Set additional button click area.
--- no click events outside stencil node
+-- Useful to restrict click outside out stencil node or scrollable content.
+--
+-- This functions calls automatically if you don't disable it in game.project: druid.no_stencil_check
 -- @tparam Button self @{Button}
 -- @tparam node zone Gui node
 -- @treturn Button Current button instance
+-- @usage
+-- button:set_click_zone("stencil_node")
 function Button.set_click_zone(self, zone)
 	self.click_zone = self:get_node(zone)
 	self.hover:set_click_zone(zone)
@@ -391,10 +477,12 @@ function Button.set_click_zone(self, zone)
 end
 
 
---- Set key-code to trigger this button
+--- Set key name to trigger this button by keyboard.
 -- @tparam Button self @{Button}
--- @tparam hash key The action_id of the key
+-- @tparam hash key The action_id of the input key
 -- @treturn Button Current button instance
+-- @usage
+-- button:set_key_trigger("key_space")
 function Button.set_key_trigger(self, key)
 	self.key_trigger = hash(key)
 
@@ -402,9 +490,11 @@ function Button.set_key_trigger(self, key)
 end
 
 
---- Get key-code to trigger this button
+--- Get current key name to trigger this button.
 -- @tparam Button self
--- @treturn hash The action_id of the key
+-- @treturn hash The action_id of the input key
+-- @usage
+-- local key_hash = button:get_key_trigger()
 function Button.get_key_trigger(self)
 	return self.key_trigger
 end
@@ -423,10 +513,12 @@ end
 
 --- Set buttom click mode to call itself inside html5 callback in user interaction event
 -- It required to do protected stuff like copy/paste text, show html keyboard, etc
--- The HTML5 button don't call any events except on_click
+-- The HTML5 button doesn't call any events except on_click event
 -- @tparam Button self
 -- @tparam[opt] boolean is_html_mode If true - button will be called inside html5 callback
 -- @treturn Button Current button instance
+-- @usage
+-- button:set_html5_user_interaction(true)
 function Button.set_html5_user_interaction(self, is_html_mode)
 	self._is_html5_mode = is_html_mode and html5
 	return self

druid/component.lua

@@ -64,7 +64,7 @@ BaseComponent.SPECIFIC_UI_MESSAGES = {
 
 
 local uid = 0
-function BaseComponent.static.get_uid()
+function BaseComponent.create_uid()
 	uid = uid + 1
 	return uid
 end
@@ -128,7 +128,7 @@ end
 
 --- Set current component nodes
 --
--- Used if your component nodes was cloned with `gui.clone_tree`
+-- Use if your component nodes was cloned with `gui.clone_tree` and you got the node tree.
 -- @function component:set_nodes
 -- @tparam BaseComponent self @{BaseComponent}
 -- @tparam table nodes BaseComponent nodes table
@@ -226,7 +226,7 @@ end
 -- @tparam BaseComponent self @{BaseComponent}
 -- @treturn string The component name
 function BaseComponent.get_name(self)
-	return self._component.name .. self:get_uid()
+	return self._component.name .. BaseComponent.create_uid()
 end
 
 
@@ -362,7 +362,7 @@ end
 
 
 --- Basic constructor of component. It will call automaticaly
--- by `BaseComponent.static.create`
+-- by `BaseComponent.create`
 -- @function component:initialize
 -- @tparam BaseComponent self @{BaseComponent}
 -- @tparam string name BaseComponent name
@@ -375,7 +375,7 @@ function BaseComponent.initialize(self, name, input_priority)
 		default_input_priority = input_priority or const.PRIORITY_INPUT,
 		is_debug = false,
 		_is_input_priority_changed = true, -- Default true for sort once time after GUI init
-		_uid = BaseComponent.get_uid()
+		_uid = BaseComponent.create_uid()
 	}
 end
 
@@ -512,11 +512,11 @@ end
 
 
 --- Create new component. It will inheritance from basic Druid component.
--- @function BaseComponent.static.create
+-- @function BaseComponent.create
 -- @tparam string name BaseComponent name
 -- @tparam[opt=DEFAULT] number input_priority The input priority. The bigger number processed first
 -- @local
-function BaseComponent.static.create(name, input_priority)
+function BaseComponent.create(name, input_priority)
 	-- Yea, inheritance here
 	local new_class = class(name, BaseComponent)
 

druid/custom/rich_text/rich_text.lua

@@ -1,6 +1,18 @@
 -- Copyright (c) 2022 Maksim Tuprikov <insality@gmail.com>. This code is licensed under MIT license
 
 --- Druid Rich Text custom component.
+-- # Overview #
+--
+--
+--
+-- # Notes #
+--
+-- @usage
+-- local RichText = require("druid.custom.rich_text.rich_text")
+-- ...
+-- self.rich_text = self.druid:new(RichText, "rich_text")
+-- self.rich_text:set_text("Hello, Druid Rich Text!")
+--
 -- @module RichText
 -- @within BaseComponent
 -- @alias druid.rich_text
@@ -21,7 +33,11 @@ local SCHEME = {
 }
 
 
-function RichText:init(template, nodes)
+--- Rich Text component constructor
+-- @tparam RichText self @{RichText}
+-- @tparam string template The Rich Text template name
+-- @tparam table nodes The node table, if prefab was copied by gui.clone_tree()
+function RichText.init(self, template, nodes)
 	self:set_template(template)
 	self:set_nodes(nodes)
 
@@ -38,7 +54,12 @@ function RichText:init(template, nodes)
 end
 
 
-function RichText:set_text(text)
+--- Set text for Rich Text
+-- @tparam RichText self @{RichText}
+-- @tparam string text The text to set
+-- @treturn table words
+-- @treturn table line_metrics
+function RichText.set_text(self, text)
 	self:clean()
 
 	local words, settings, line_metrics = rich_text.create(text, self._settings)
@@ -56,6 +77,9 @@ function RichText:on_remove()
 end
 
 
+--- Get all words, which has a passed tag
+-- @tparam string tag
+-- @treturn table Words
 function RichText:tagged(tag)
 	if not self._words then
 		return
@@ -65,6 +89,8 @@ function RichText:tagged(tag)
 end
 
 
+--- Get all current words.
+-- @treturn table Words
 function RichText:get_words()
 	return self._words
 end
@@ -99,6 +125,7 @@ function RichText:_create_settings()
 end
 
 
+--- Clear all created words.
 function RichText:clean()
 	if self._words then
 		rich_text.remove(self._words)

druid/extended/input.lua

@@ -115,7 +115,7 @@ end
 
 --- Component init function
 -- @tparam Input self @{Input}
--- @tparam node click_node Button node to enabled input component
+-- @tparam node click_node Node to enabled input component
 -- @tparam node|Text text_node Text node what will be changed on user input. You can pass text component instead of text node name @{Text}
 -- @tparam[opt] number keyboard_type Gui keyboard type for input field
 function Input.init(self, click_node, text_node, keyboard_type)

druid/system/druid_instance.lua

@@ -288,7 +288,7 @@ function DruidInstance.final(self)
 end
 
 
---- Remove component from Druid instance.
+--- Remove created component from Druid instance.
 --
 -- Component `on_remove` function will be invoked, if exist.
 -- @tparam DruidInstance self