All basic components declared with explicit way

druid/druid.lua

@@ -1,7 +1,12 @@
 --- Druid UI Library.
--- Component based UI library to make your life easier.
--- Contains a lot of base components and give API
--- to create your own rich components.
+-- Powerful Defold component based UI library. Use standart
+-- components or make your own game-specific to make amazing
+-- GUI in your games.
+--
+-- Contains the several basic components and examples
+-- to how to do your custom complex components to
+-- separate UI game logic to small files
+--
 -- @module druid
 
 local const = require("druid.const")
@@ -13,47 +18,12 @@ local M = {}
 local log = settings.log
 
 
---- Basic components
-M.components = {
-	button = require("druid.base.button"),
-	blocker = require("druid.base.blocker"),
-	back_handler = require("druid.base.back_handler"),
-	text = require("druid.base.text"),
-	locale = require("druid.base.locale"),
-	timer = require("druid.base.timer"),
-	progress = require("druid.base.progress"),
-	grid = require("druid.base.grid"),
-	scroll = require("druid.base.scroll"),
-	slider = require("druid.base.slider"),
-	checkbox = require("druid.base.checkbox"),
-	checkbox_group = require("druid.base.checkbox_group"),
-	radio_group = require("druid.base.radio_group"),
-
-	-- TODO:
-	-- input - text input
-	-- infinity_scroll -- to handle big data scroll
-
-	progress_rich = require("druid.rich.progress_rich"),
-
-	-- TODO: Examples:
-	-- Slider menu like clash royale
-}
-
-
-local function register_basic_components()
-	for k, v in pairs(M.components) do
-		if not druid_instance["new_" .. k] then
-			M.register(k, v)
-		else
-			log("Basic component", k, "already registered")
-		end
-	end
-end
-
-
---- Register external module
+--- Register external druid component.
+-- After register you can create the component with
+-- druid_instance:new_{name}. For example `druid:new_button(...)`
+-- @function druid:register
 -- @tparam string name module name
--- @tparam table module lua table with module
+-- @tparam table module lua table with component
 function M.register(name, module)
 	-- TODO: Find better solution to creating elements?
 	-- Possibly: druid.new(druid.BUTTON, etc?)
@@ -66,23 +36,30 @@ function M.register(name, module)
 end
 
 
---- Create Druid instance for creating components
--- @return instance with all ui components
+--- Create Druid instance.
+-- @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
 function M.new(context, style)
-	if register_basic_components then
-		register_basic_components()
-		register_basic_components = false
-	end
-
 	return druid_instance(context, style)
 end
 
 
+-- Set new default style.
+-- @function druid.set_default_style
+-- @tparam table style Druid style module
 function M.set_default_style(style)
 	settings.default_style = style
 end
 
 
+-- Set text function.
+-- 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(callback)
+-- @tparam function callback Get localized text function
 function M.set_text_function(callback)
 	settings.get_text = callback or const.EMPTY_FUNCTION
 	-- TODO: Update all localized text
@@ -90,6 +67,11 @@ function M.set_text_function(callback)
 end
 
 
+-- Set sound function.
+-- Component will call this function to
+-- play sound by sound_id
+-- @function druid.set_sound_function
+-- @tparam function callback Sound play callback
 function M.set_sound_function(callback)
 	settings.play_sound = callback or const.EMPTY_FUNCTION
 end

druid/system/druid_instance.lua

@@ -1,8 +1,43 @@
+--- Druid main class. Create instance of this
+-- to start creating components
+-- @module druid_instance
+-- @see druid.button
+-- @see druid.blocker
+-- @see druid.back_handler
+-- @see druid.text
+-- @see druid.locale
+-- @see druid.timer
+-- @see druid.progress
+-- @see druid.grid
+-- @see druid.scroll
+-- @see druid.slider
+-- @see druid.checkbox
+-- @see druid.checkbox_group
+-- @see druid.radio_group
+
 local const = require("druid.const")
 local druid_input = require("druid.helper.druid_input")
 local settings = require("druid.system.settings")
 local class = require("druid.system.middleclass")
 
+local button = require("druid.base.button")
+local blocker = require("druid.base.blocker")
+local back_handler = require("druid.base.back_handler")
+local text = require("druid.base.text")
+local locale = require("druid.base.locale")
+local timer = require("druid.base.timer")
+local progress = require("druid.base.progress")
+local grid = require("druid.base.grid")
+local scroll = require("druid.base.scroll")
+local slider = require("druid.base.slider")
+local checkbox = require("druid.base.checkbox")
+local checkbox_group = require("druid.base.checkbox_group")
+local radio_group = require("druid.base.radio_group")
+-- local input - require("druid.base.input")
+-- local infinity_scroll = require("druid.base.infinity_scroll")
+local progress_rich = require("druid.rich.progress_rich")
+
+-- @classmod Druid
 local Druid = class("druid.druid_instance")
 
 
@@ -19,12 +54,9 @@ local function input_init(self)
 end
 
 
--- Create the component
+-- Create the component itself
 local function create(self, instance_class)
-	---@class component
 	local instance = instance_class()
-
-	-- Component context, self from component creation
 	instance:setup_component(self._context, self._style)
 
 	self.components[const.ALL] = self.components[const.ALL] or {}
@@ -75,7 +107,10 @@ local function match_event(action_id, events)
 end
 
 
---- Druid constructor
+--- Druid class constructor
+-- @function druid:initialize
+-- @tparam context table Druid context. Usually it is self of script
+-- @tparam style table Druid style module
 function Druid.initialize(self, context, style)
 	self._context = context
 	self._style = style or settings.default_style
@@ -83,9 +118,12 @@ function Druid.initialize(self, context, style)
 end
 
 
---- Create new component inside druid instance
-function Druid.create(self, instance_class, ...)
-	local instance = create(self, instance_class)
+--- Create new druid component
+-- @function druid:create
+-- @tparam Component component Component module
+-- @tparam args ... Other component params to pass it to component:init function
+function Druid.create(self, component, ...)
+	local instance = create(self, component)
 
 	if instance.init then
 		instance:init(...)
@@ -95,8 +133,10 @@ function Druid.create(self, instance_class, ...)
 end
 
 
---- Remove component from druid instance
--- It will call on_remove on component, if exist
+--- Remove component from druid instance.
+-- Component `on_remove` function will be invoked, if exist.
+-- @function druid:remove
+-- @tparam Component component Component instance
 function Druid.remove(self, component)
 	local all_components = self.components[const.ALL]
 	for i = #all_components, 1, -1 do
@@ -123,8 +163,9 @@ function Druid.remove(self, component)
 end
 
 
---- Druid instance update function
--- @function druid:update(dt)
+--- Druid update function
+-- @function druid:update
+-- @tparam number dt Delta time
 function Druid.update(self, dt)
 	local components = self.components[const.ON_UPDATE]
 	if components then
@@ -135,8 +176,10 @@ function Druid.update(self, dt)
 end
 
 
---- Druid instance on_input function
--- @function druid:on_input(action_id, action)
+--- Druid on_input function
+-- @function druid:on_input
+-- @tparam hash action_id Action_id from on_input
+-- @tparam table action Action from on_input
 function Druid.on_input(self, action_id, action)
 	-- TODO: расписать отличия ON_SWIPE и ON_INPUT
 	-- Почему-то некоторые используют ON_SWIPE, а логичнее ON_INPUT? (blocker, slider)
@@ -168,8 +211,11 @@ function Druid.on_input(self, action_id, action)
 end
 
 
---- Druid instance on_message function
--- @function druid:on_message(message_id, message, sender)
+--- Druid on_message function
+-- @function druid:on_message
+-- @tparam hash message_id Message_id from on_message
+-- @tparam table message Message from on_message
+-- @tparam hash sender Sender from on_message
 function Druid.on_message(self, message_id, message, sender)
 	local specific_ui_message = const.SPECIFIC_UI_MESSAGES[message_id]
 	if specific_ui_message then
@@ -189,4 +235,132 @@ function Druid.on_message(self, message_id, message, sender)
 end
 
 
+--- Create button basic component
+-- @function druid:new_button
+-- @tparam args ... button init args
+-- @treturn Component button component
+function Druid.new_button(self, ...)
+	return Druid.create(self, button, ...)
+end
+
+
+--- Create blocker basic component
+-- @function druid:new_blocker
+-- @tparam args ... blocker init args
+-- @treturn Component blocker component
+function Druid.new_blocker(self, ...)
+	return Druid.create(self, blocker, ...)
+end
+
+
+--- Create back_handler basic component
+-- @function druid:new_back_handler
+-- @tparam args ... back_handler init args
+-- @treturn Component back_handler component
+function Druid.new_back_handler(self, ...)
+	return Druid.create(self, back_handler, ...)
+end
+
+
+--- Create text basic component
+-- @function druid:new_text
+-- @tparam args ... text init args
+-- @treturn Component text component
+function Druid.new_text(self, ...)
+	return Druid.create(self, text, ...)
+end
+
+
+--- Create locale basic component
+-- @function druid:new_locale
+-- @tparam args ... locale init args
+-- @treturn Component locale component
+function Druid.new_locale(self, ...)
+	return Druid.create(self, locale, ...)
+end
+
+
+--- Create timer basic component
+-- @function druid:new_timer
+-- @tparam args ... timer init args
+-- @treturn Component timer component
+function Druid.new_timer(self, ...)
+	return Druid.create(self, timer, ...)
+end
+
+
+--- Create progress basic component
+-- @function druid:new_progress
+-- @tparam args ... progress init args
+-- @treturn Component progress component
+function Druid.new_progress(self, ...)
+	return Druid.create(self, progress, ...)
+end
+
+
+--- Create grid basic component
+-- @function druid:new_grid
+-- @tparam args ... grid init args
+-- @treturn Component grid component
+function Druid.new_grid(self, ...)
+	return Druid.create(self, grid, ...)
+end
+
+
+--- Create scroll basic component
+-- @function druid:new_scroll
+-- @tparam args ... scroll init args
+-- @treturn Component scroll component
+function Druid.new_scroll(self, ...)
+	return Druid.create(self, scroll, ...)
+end
+
+
+--- Create slider basic component
+-- @function druid:new_slider
+-- @tparam args ... slider init args
+-- @treturn Component slider component
+function Druid.new_slider(self, ...)
+	return Druid.create(self, slider, ...)
+end
+
+
+--- Create checkbox basic component
+-- @function druid:new_checkbox
+-- @tparam args ... checkbox init args
+-- @treturn Component checkbox component
+function Druid.new_checkbox(self, ...)
+	return Druid.create(self, checkbox, ...)
+end
+
+
+--- Create checkbox_group basic component
+-- @function druid:new_checkbox_group
+-- @tparam args ... checkbox_group init args
+-- @treturn Component checkbox_group component
+function Druid.new_checkbox_group(self, ...)
+	return Druid.create(self, checkbox_group, ...)
+end
+
+
+--- Create radio_group basic component
+-- @function druid:new_radio_group
+-- @tparam args ... radio_group init args
+-- @treturn Component radio_group component
+function Druid.new_radio_group(self, ...)
+	return Druid.create(self, radio_group, ...)
+end
+
+
+--- Create progress_rich basic component
+-- @function druid:new_progress_rich
+-- @tparam args ... progress_rich init args
+-- @treturn Component progress_rich component
+function Druid.new_progress_rich(self, ...)
+	return Druid.create(self, progress_rich, ...)
+end
+
+
+
+
 return Druid

druid/system/settings.lua

@@ -1,5 +1,6 @@
 --- Druid settings file
 -- @module settings
+-- @local
 
 local M = {}