Update docs

README.md

@@ -7,14 +7,14 @@
 [![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 framework. Use huge list of embedeed **Druid** components or make your own game-specific components with ease to make stunning and customizable GUI in your games.
+**Druid** - powerful **Defold** component UI framework that empowers developers to create stunning and customizable GUIs by leveraging a wide range of embedded components or effortlessly designing their own game-specific components.
 
 
 ## Setup
 
 ### Dependency
 
-You can use the **Druid** extension in your own project by adding this project as a [Defold library dependency](https://www.defold.com/manuals/libraries/). Open your `game.project` file and in the dependencies field under project add:
+To integrate the **Druid** extension into your own project, add this project as a [dependency](https://www.defold.com/manuals/libraries/) in your **Defold** game. Open your `game.project` file and add the following line to the dependencies field under the project section:
 
 **Druid v0.10.3**
 > [https://github.com/Insality/druid/archive/refs/tags/0.10.3.zip](https://github.com/Insality/druid/archive/refs/tags/0.10.3.zip)
@@ -22,27 +22,27 @@ 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 bindings. For custom input bindings see the Input Binding section in **_[Advanced Setup](docs_md/advanced-setup.md)_**.
+**Druid** utilizes the `/builtins/input/all.input_binding` input bindings. For custom input bindings, refer to the Input Binding section in the  **_[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.
+If you need to customize **Druid** according to your specific requirements, you can refer to the **_[Advanced Setup](docs_md/advanced-setup.md)_** section.
 
 
 ## Usage
 
 ### Basic usage
 
-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*.
+To utilize **Druid**, begin by creating a **Druid** instance to instantiate components and include the main functions of **Druid**: *update*, *final*, *on_message*, and *on_input*.
 
-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.
+When using **Druid** components, provide a node name string as an argument. If you don't have the node name available in some cases, you can pass `gui.get_node()` instead.
 
-All **Druid** and component methods are called with `:` like `self.druid:new_button()`.
+All **Druid** and component methods are invoked using the `:` operator, such as `self.druid:new_button()`.
 
 ```lua
 local druid = require("druid.druid")
 
 -- All component callbacks pass "self" as first argument
--- This self is a context data passed in `druid.new(context)`
+-- This "self" is a context data passed in `druid.new(context)`
 local function on_button_callback(self)
     print("The button clicked!")
 end
@@ -52,22 +52,22 @@ function init(self)
     self.button = self.druid:new_button("button_node_name", on_button_callback)
 end
 
--- Final is a required function for a correct Druid workflow
+-- "final" is a required function for the correct Druid workflow
 function final(self)
     self.druid:final()
 end
 
--- The update used in progress bar, scroll and timer basic components
+-- "update" is 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
+-- "on_message" is 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
+-- "on_input" is used in almost all Druid components
 function on_input(self, action_id, action)
     return self.druid:on_input(action_id, action)
 end
@@ -79,19 +79,21 @@ For all **Druid** instance functions, [see here](https://insality.github.io/drui
 
 ### 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.
+**Druid** offers a wide range of components and functions. To facilitate usage, **Druid** provides comprehensive API documentation with examples and annotations.
+
+Start reading the API documentation [here](hhttps://insality.github.io/druid/modules/Druid.html).
 
-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).
+[EmmyLua](https://emmylua.github.io/annotation.html) is a Lua annotation library. It is a useful tool for enabling Lua code autocompletion in editors such as [VSCode](https://github.com/EmmyLua/VSCode-EmmyLua) and [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.
+Since dependencies cannot be processed by external editors, to use the generated EmmyLua annotations, you should copy the _druid/annotations.lua_ file to your project.
 
-For EmmyLua it will be enough. Remember you can _restart emmylua server_ for refresh the changes, if something goes wrong.
+For EmmyLua, this will be sufficient. Remember that you can restart the EmmyLua server to refresh the changes if something goes wrong.
+
+After the annotations are processed, you should specify the type of "Druid" in the "require" statement:
 
-After the annotations is processed, you should point the type of Druid in requires:
 ```lua
 ---@type druid
 local druid = require("druid.druid")
@@ -101,16 +103,12 @@ local druid = require("druid.druid")
 
 <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.
+If you want to create your own components, refer to the [Create Custom Components](docs_md/create-custom-components.md) section in the documentation.
 
-The custom components is the most powerful feature of **Druid**. You can create your own components with ease and use it in your game.
+Custom components are one of the most powerful features of **Druid**. They allow you to create your own components effortlessly and utilize them in your game.
 
 
 ## Druid Components
@@ -170,26 +168,25 @@ You can subscribe several callbacks to a single event.
 
 ## Details
 
-- **Druid** input goes as stack. Last created button will be checked first. Create your input GUI component from back to front.
+- **Druid** processes input in a stack-based manner. The most recently created button will be checked first. Create your input GUI components from back to front.
-- 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)
+- Remember to include `return` in the `on_input` function: `return self.druid:on_input()`. This is necessary if you have multiple input sources (multiple Druid instances, other input systems, etc.).
-- Druid automatically call _acquire_input_focus_ if you have input components. So you don't required to call it manually.
+- Druid automatically calls `acquire_input_focus` if you have input components. Therefore, manual calling of `acquire_input_focus` is not required.
-- If you want to delete a **Druid** component node, don't forget to remove it via `druid:remove(component)`
+- When deleting a **Druid** component node, make sure to remove it using `druid:remove(component)`.
 
-[See full FAQ here](docs_md/FAQ.md)
+[See the full FAQ here](docs_md/FAQ.md)
 
 
 ## Examples
 
 ### HTML5 Live Examples
 
-Try the [**HTML5 version**](https://insality.github.io/druid/druid/) of the **Druid** example app
+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**
+Each example page provides a direct link to the corresponding example code, making it easier for you to understand how to use **Druid**.
 
+### Code Examples
 
-### Code examples
+Refer to the [**example folder**](https://github.com/Insality/druid/tree/develop/example) for code examples demonstrating how to use **Druid**.
-
-See the [**example folder**](https://github.com/Insality/druid/tree/develop/example) for examples of how to use **Druid**
 
 
 ## Documentation

docs_md/advanced-setup.md

@@ -1,29 +1,30 @@
-# Advanced Druid setup
+# Advanced Druid Setup
 
 
-## Input bindings
+## Input Bindings
 
-As default input bindings **Druid** uses the `/builtins/input/all.input_binding`.
+By default, **Druid** utilizes the `/builtins/input/all.input_binding` for input bindings.
 
 **Druid** requires the following input bindings:
 
-- Mouse trigger - `Button 1` -> `touch` _For basic input components_
+- Mouse trigger: `Button 1` -> `touch` (for basic input components)
-- Mouse trigger - `Wheel up` -> `mouse_wheel_up` _For scroll component_
+- Mouse trigger: `Wheel up` -> `mouse_wheel_up` (for Scroll component)
-- Mouse trigger - `Wheel down` -> `mouse_wheel_down` _For scroll component_
+- Mouse trigger: `Wheel down` -> `mouse_wheel_down` (for Scroll component)
-- Key trigger - `Backspace` -> `key_backspace`  _For back_handler component, input component_
+- Key trigger: `Backspace` -> `key_backspace` (for BackHandler component, input component)
-- Key trigger - `Back` -> `key_back`  _For back_handler component, Android back button, input component_
+- Key trigger: `Back` -> `key_back` (for BackHandler component, Android back button, input component)
-- Key trigger - `Enter` -> `key_enter` _For input component, optional_
+- Key trigger: `Enter` -> `key_enter` (for Input component, optional)
-- Key trigger - `Esc` -> `key_esc` _For input component, optional_
+- Key trigger: `Esc` -> `key_esc` (for Input component, optional)
-- Touch triggers - `Touch multi` -> `touch_multi` _For scroll component_
+- Touch triggers: `Touch multi` -> `touch_multi` (for Scroll component)
 
 ![](media/input_binding_2.png)
 ![](media/input_binding_1.png)
 
 
-## Change key bindings [optional]
+## Changing Key Bindings (optional)
-If you have to use your own key bindings (and key name), you can change it in your *game.project* file.
 
-Here is current default values for key bindings:
+If you need to use your own key bindings or key names, you can modify them in your *game.project* file.
+
+Here are the default values for key bindings:
 ```
 [druid]
 input_text = text
@@ -39,22 +40,22 @@ input_scroll_down = mouse_wheel_down
 ```
 
 
-## Input capturing [optional]
+## Input Capturing (optional)
 
-By default, **Druid** will auto-capture input focus, if any input component will be created. So you don't need to call `msg.post(".", "acquire_input_focus")`
+By default, **Druid** automatically captures input focus if any input component is created. Therefore, you do not need to call `msg.post(".", "acquire_input_focus")`.
 
-If you don't need this behaviour, you can disable it by setting `druid.no_auto_input` field in _game.project_:
+If you do not require this behavior, you can disable it by setting the `druid.no_auto_input` field in the _game.project_ file:
 ```
 [druid]
 no_auto_input = 1
 ```
 
 
-## Template name check [optional]
+## Template Name Check (optional)
 
-By default, **Druid** will auto check the parent component template name to build the full template name for component.
+By default, **Druid** automatically checks the parent component's template name to construct the full template name for the component. It's used in user custom components.
 
-If for some reason you want to pass the full template name by yourself, you can disable it by setting `druid.no_auto_template` field in _game.project_:
+If, for some reason, you want to pass the full template name manually, you can disable this feature by setting the `druid.no_auto_template` field in the _game.project_ file:
 
 ```
 [druid]
@@ -62,47 +63,46 @@ no_auto_template = 1
 ```
 
 
-## Stencil check [optional]
+## 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.
+When creating input components inside stencil nodes, **Druid** automatically sets up `component:set_click_zone()` during the _late_init_ component step to restrict input clicks outside of the stencil zone. This is particularly useful for buttons inside scroll stencil nodes.
-For example: button inside scroll stencil nodes.
 
-To disable this feature add next field in your _game.project_ file
+To disable this feature, add the following field to your _game.project_ file:
 ```
 [druid]
 no_stencil_check = 1
 ```
 
 
-## Code bindings [optional]
+## Code Bindings (optional)
 
-Adjust **Druid** settings, if needed:
+Adjust **Druid** settings as needed:
 ```lua
 local druid = require("druid.druid")
 
 -- Used for button component and custom components
--- Callback should play sound by name: function(sound_id) ... end
+-- The callback should play the sound by name: function(sound_id) ... end
 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
+-- The callback should return the localized string by locale ID: function(locale_id) ... end
 druid.set_text_function(function(locale_id)
 	-- return lang.get(locale_id)
 end)
 
--- Used for change default Druid style
+-- Used to change the default Druid style
 druid.set_default_style(your_style)
 
--- Call this function on language changing in the game,
+-- Call this function when the language changes 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:
+-- to capture 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)

druid/annotations.lua

@@ -231,7 +231,7 @@ function druid__button.set_enabled(self, state) end
 function druid__button.set_key_trigger(self, key) end
 
 --- Set Button mode to work inside user HTML5 interaction event.
---- It's required to make protected things like copy & paste text, show mobile keyboard, etc  The HTML5 button's doesn't call any events except on_click event.  If the game is not HTML, HTML html mode will be not enabled
+--- It's required to make protected things like copy & paste text, show mobile keyboard, etc  The HTML5 button's doesn't call any events except on_click event.  If the game is not HTML, html mode will be not enabled
 ---@param self druid.button
 ---@param is_web_mode boolean If true - button will be called inside html5 callback
 ---@return druid.button Current button instance
@@ -1008,10 +1008,10 @@ function druid__scroll.get_percent(self) end
 ---@return vector3 Available scroll size
 function druid__scroll.get_scroll_size(self) end
 
---- Scroll constructor
+--- @{Scroll} constructor
 ---@param self druid.scroll @{Scroll}
----@param view_node node GUI view scroll node
+---@param view_node string|node GUI view scroll node
----@param content_node node GUI content scroll node
+---@param content_node string|node GUI content scroll node
 function druid__scroll.init(self, view_node, content_node) end
 
 --- Return if scroll have inertion.

druid/base/button.lua

@@ -1,13 +1,13 @@
 -- Copyright (c) 2021 Maksim Tuprikov <insality@gmail.com>. This code is licensed under MIT license
 
 --- Druid Component for Handling User Click Interactions: Click, Long Click, Double Click, and More.
-
+--
--- ## Overview ##
+-- # Overview #
 --
 -- This component provides a versatile solution for handling user click interactions.
 -- It allows you to make any GUI node clickable and define various callbacks for different types of clicks.
 --
--- ## Notes ##
+-- # Notes #
 --
 -- • The click callback will not trigger if the cursor moves outside the node's
 -- area between the pressed and released states.
@@ -522,7 +522,7 @@ end
 -- It's required to make protected things like copy & paste text, show mobile keyboard, etc
 -- The HTML5 button's doesn't call any events except on_click event.
 --
--- If the game is not HTML, HTML html mode will be not enabled
+-- If the game is not HTML, html mode will be not enabled
 -- @tparam Button self
 -- @tparam[opt] boolean is_web_mode If true - button will be called inside html5 callback
 -- @treturn Button Current button instance

druid/base/scroll.lua

@@ -1,6 +1,7 @@
 -- Copyright (c) 2021 Maksim Tuprikov <insality@gmail.com>. This code is licensed under MIT license
 
--- ## Overview ##
+--- Component to handle scroll content.
+-- # Overview #
 --
 -- The Scroll component is designed to handle scrollable content and consists of two nodes: the scroll parent and the scroll input.
 --
@@ -11,7 +12,7 @@
 -- The initial scroll size can be set by adjusting the size of the scroll parent.
 -- If the size of the scroll parent is smaller than the scroll input size, scrolling is not available.
 --
--- ## Notes ##
+-- # Notes #
 --
 -- • By default, the scroll style includes inertia and extra size for a stretching effect.
 -- These settings can be adjusted using the scroll style settings.

example/example.gui_script

@@ -311,5 +311,5 @@ end
 
 
 function on_input(self, action_id, action)
-	self.druid:on_input(action_id, action)
+	return self.druid:on_input(action_id, action)
 end