Move swipe to extended, update docs

druid/druid.lua

@@ -1,20 +1,49 @@
 -- Copyright (c) 2021 Maksim Tuprikov <insality@gmail.com>. This code is licensed under MIT license
 
---- Druid UI Library.
--- Powerful Defold component based UI library. Use standart
--- components or make your own game-specific components to
--- make amazing GUI in your games.
+--- Druid UI Component Framework.
+-- # Overview #
 --
--- Contains the several basic components and examples
--- to how to do your custom complex components to
--- separate UI game logic to small files
+-- 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.
 --
---    require("druid.druid")
---    function init(self)
---        self.druid = druid.new(self)
---    end
+-- To start use Druid, check the Basic Usage below.
 --
--- @module druid
+-- # Tech Info #
+--
+-- - Each Druid keeps the self context from constructor to pass it into each Druid callback
+--
+-- See next: @{DruidInstance}
+--
+-- @usage
+-- local druid = require("druid.druid")
+--
+-- local function button_callback(self)
+--     print("Button was clicked!")
+-- end
+--
+-- function init(self)
+--     self.druid = druid.new(self)
+--     self.druid:new_button("button_node_name", button_callback)
+-- end
+--
+-- function final(self)
+--     self.druid:final()
+-- end
+--
+-- function update(self, dt)
+--     self.druid:update(dt)
+-- end
+--
+-- function on_message(self, message_id, message, sender)
+--     self.druid:on_message(message_id, message, sender)
+-- end
+--
+-- function on_input(self, action_id, action)
+--     return self.druid:on_input(action_id, action)
+-- end
+--
+-- @module Druid
 
 local const = require("druid.const")
 local base_component = require("druid.component")
@@ -38,12 +67,19 @@ local function get_druid_instances()
 end
 
 
---- Register external druid component.
--- After register you can create the component with
--- druid_instance:new_{name}. For example `druid:new_button(...)`
--- @function druid:register
+--- Register new external Druid component.
+--
+-- You can register your own components to create it with druid:new_{name} function
+-- For example, you can register your own component "my_component" and create it with druid:new_my_component(...)
+-- @function druid.register
 -- @tparam string name module name
 -- @tparam table module lua table with component
+-- @usage
+-- local my_component = require("path.to.my.component")
+-- druid.register("my_component", my_component)
+-- ...
+-- local druid = druid.new(self)
+-- local component_instance = self.druid:new_my_component(...)
 function M.register(name, module)
 	-- TODO: Find better solution to creating elements?
 	-- Current way is very implicit
@@ -53,11 +89,17 @@ function M.register(name, module)
 end
 
 
---- Create Druid instance.
+--- Create new Druid instance to create GUI components.
 -- @function druid.new
--- @tparam table context Druid context. Usually it is self of script
--- @tparam[opt] table style Druid style module
--- @treturn druid_instance Druid instance
+-- @tparam table context Druid context. Usually it is *self* of *gui_script. It passes into all Druid callbacks
+-- @tparam[opt] table style Druid style table to override style params for this Druid instance
+-- @treturn druid_instance Druid instance @{DruidInstance}
+-- @usage
+-- local druid = require("druid.druid")
+--
+-- function init(self)
+--    self.druid = druid.new(self)
+-- end
 function M.new(context, style)
 	if settings.default_style == nil then
 		M.set_default_style(default_style)
@@ -69,40 +111,60 @@ function M.new(context, style)
 end
 
 
---- Set new default style.
+--- Set your own default style for all Druid instances.
+--
+-- To create your own style file, copy the default style file and change it.
+-- Register new style before your Druid instances creation.
 -- @function druid.set_default_style
 -- @tparam table style Druid style module
+-- @usage
+-- local my_style = require("path.to.my.style")
+-- druid.set_default_style(my_style)
 function M.set_default_style(style)
 	settings.default_style = style or {}
 end
 
 
---- Set text function
--- Druid locale component will call this function
--- to get translated text. After set_text_funtion
+--- Set text function for LangText component.
+--
+-- Druid locale component will call this function to get translated text. After set_text_funtion
 -- all existing locale component will be updated
 -- @function druid.set_text_function
 -- @tparam function callback Get localized text function
+-- @usage
+-- druid.set_text_function(function(text_id)
+--    return lang_data[text_id] -- Replace with your real function
+-- end)
 function M.set_text_function(callback)
 	settings.get_text = callback or const.EMPTY_FUNCTION
 	M.on_language_change()
 end
 
 
---- Set sound function.
--- Component will call this function to
--- play sound by sound_id
+--- Set Druid sound function to play UI sounds if used.
+--
+-- Set function to play sound by sound_id. It used in Button click and play "click" sound.
+-- Also can be used by play sound in your custom components (see default Druid style file for example)
 -- @function druid.set_sound_function
 -- @tparam function callback Sound play callback
+-- @usage
+-- druid.set_sound_function(function(sound_id)
+--     sound.play(sound_id) -- Replace with your real function
+-- end)
 function M.set_sound_function(callback)
 	settings.play_sound = callback or const.EMPTY_FUNCTION
 end
 
 
---- Callback on global window event.
--- Used to trigger on_focus_lost and on_focus_gain
+--- Set window callback to enable *on_focus_gain* and *on_focus_lost* functions.
+--
+-- Used to trigger on_focus_lost and on_focus_gain in Druid components
 -- @function druid.on_window_callback
 -- @tparam string event Event param from window listener
+-- @usage
+-- window.set_listener(function(_, event)
+--    druid.on_window_callback(event)
+-- end)
 function M.on_window_callback(event)
 	local instances = get_druid_instances()
 
@@ -126,9 +188,12 @@ function M.on_window_callback(event)
 end
 
 
---- Callback on global language change event.
--- Use to update all lang texts
+--- Call this on game language change.
+--
+-- This function will update all LangText components
 -- @function druid.on_language_change
+-- @usage
+-- druid.on_language_change()
 function M.on_language_change()
 	local instances = get_druid_instances()