Update ldoc comments

druid/base/back_handler.lua

@@ -1,4 +1,4 @@
---- Component to handle back key
+--- Component to handle back key (android, backspace)
 -- @module base.back_handler
 
 local const = require("druid.const")
@@ -9,9 +9,10 @@ M.interest = {
 }
 
 --- Component init function
--- @tparam table self component instance
--- @tparam callback callback on back button
--- @tparam[opt] params callback argument
+-- @function back_handler:init
+-- @tparam table self Component instance
+-- @tparam callback callback On back button
+-- @tparam[opt] params Callback argument
 function M.init(self, callback, params)
 	self.event = const.ACTION_BACK
 	self.callback = callback
@@ -20,6 +21,7 @@ end
 
 
 --- Input handler for component
+-- @function back_handler:on_input
 -- @tparam string action_id on_input action id
 -- @tparam table action on_input action
 function M.on_input(self, action_id, action)

druid/base/button.lua

@@ -22,6 +22,14 @@ M.DEFAULT_ACTIVATE_SCALE = vmath.vector3(1, 1, 1)
 M.DEFAULT_ACTIVATION_TIME = 0.2
 
 
+--- Component init function
+-- @function button:init
+-- @tparam table self Component instance
+-- @tparam node node Gui node
+-- @tparam function callback Button callback
+-- @tparam[opt] table params Button callback params
+-- @tparam[opt] node anim_node Button anim node (node, if not provided)
+-- @tparam[opt] string event Button react event, const.ACTION_TOUCH by default
 function M.init(self, node, callback, params, anim_node, event)
 	self.node = helper.node(node)
 	self.event = const.ACTION_TOUCH
@@ -79,9 +87,6 @@ local function on_button_release(self)
 end
 
 
---- Set text to text field
--- @param action_id - input action id
--- @param action - input action
 function M.on_input(self, action_id, action)
 	if not helper.is_enabled(self.node) then
 		return false
@@ -197,6 +202,9 @@ function M.activate(self, is_animate, callback)
 end
 
 
+--- Disable all button animations
+-- @function button:disable_animation
+-- @tparam table self Component instance
 function M.disable_animation(self)
 	self.hover_anim = false
 	self.tap_anim = nil
@@ -204,8 +212,11 @@ function M.disable_animation(self)
 end
 
 
---- Set additional node, what need to be clicked on button click
--- Used, if need setup, what button can be clicked only in special zone
+--- Strict button click area. Useful for
+-- no click events outside stencil node
+-- @function button:set_click_zone
+-- @tparam table self Component instance
+-- @tparam node zone Gui node
 function M.set_click_zone(self, zone)
 	self.click_zone = helper.node(zone)
 end

druid/base/progress.lua

@@ -1,4 +1,4 @@
---- Component to handle progress bars
+--- Basic progress bar component
 -- @module base.progress
 
 local const = require("druid.const")
@@ -12,25 +12,28 @@ M.interest = {
 	const.ON_UPDATE,
 }
 
-local PROP_Y = "y"
-local PROP_X = "x"
 
-
-function M.init(self, name, key, init_value)
-	if key ~= PROP_X and key ~= PROP_Y then
+--- Component init function
+-- @function progress:init
+-- @tparam table self Component instance
+-- @tparam string|node node Progress bar fill node or node name
+-- @tparam string key Progress bar direction (x or y)
+-- @tparam number init_value Initial value of progress bar
+function M.init(self, node, key, init_value)
+	if key ~= const.SIDE.X and key ~= const.SIDE.Y then
 		settings.log("progress component: key must be 'x' or 'y'. Passed:", key)
-		key = PROP_X
+		key = const.SIDE.X
 	end
 
 	self.prop = hash("scale."..key)
 	self.key = key
 
-	self.node = helper.node(name)
+	self.node = helper.node(node)
 	self.scale = gui.get_scale(self.node)
 	self.size = gui.get_size(self.node)
 	self.max_size = self.size[self.key]
 	self.slice = gui.get_slice9(self.node)
-	if key == PROP_X then
+	if key == const.SIDE.X then
 		self.slice_size = self.slice.x + self.slice.z
 	else
 		self.slice_size = self.slice.y + self.slice.w
@@ -83,38 +86,54 @@ end
 
 
 --- Fill a progress bar and stop progress animation
+-- @function progress:empty
+-- @tparam table self Component instance
 function M.fill(self)
 	set_bar_to(self, 1, true)
 end
 
 
---- To empty a progress bar
+--- Empty a progress bar
+-- @function progress:empty
+-- @tparam table self Component instance
 function M.empty(self)
 	set_bar_to(self, 0, true)
 end
 
 
---- Set fill a progress bar to value
--- @param to - value between 0..1
+--- Instant fill progress bar to value
+-- @function progress:set_to
+-- @tparam table self Component instance
+-- @tparam number to Progress bar value, from 0 to 1
 function M.set_to(self, to)
 	set_bar_to(self, to)
 end
 
 
+--- Return current progress bar value
+-- @function progress:get
+-- @tparam table self Component instance
 function M.get(self)
 	return self.last_value
 end
 
 
-function M.set_steps(self, steps, step_callback)
+--- Set points on progress bar to fire the callback
+-- @function progress:set_steps
+-- @tparam table self Component instance
+-- @tparam table steps Array of progress bar values
+-- @tparam function callback Callback on intersect step value
+function M.set_steps(self, steps, callback)
 	self.steps = steps
-	self.step_callback = step_callback
+	self.step_callback = callback
 end
 
 
 --- Start animation of a progress bar
--- @param to - value between 0..1
--- @param callback - callback when progress ended if need
+-- @function progress:to
+-- @tparam table self Component instance
+-- @tparam number to value between 0..1
+-- @tparam[opt] function callback Callback on animation ends
 function M.to(self, to, callback)
 	to = helper.clamp(to, 0, 1)
 	-- cause of float error

druid/base/scroll.lua

@@ -7,15 +7,13 @@ local settings = require("druid.settings").scroll
 
 local M = {}
 
-local SIDE_X = "x"
-local SIDE_Y = "y"
-
 M.interest = {
 	const.ON_UPDATE,
 	const.ON_SWIPE,
 }
 
 -- Global on all scrolls
+-- TODO: remove it
 M.current_scroll = nil
 
 
@@ -280,14 +278,11 @@ function M.on_input(self, action_id, action)
 			if not M.current_scroll and dist >= settings.DEADZONE then
 				local dx = math.abs(inp.start_x - action.x)
 				local dy = math.abs(inp.start_y - action.y)
-				if dx > dy then
-					inp.side = SIDE_X
-				else
-					inp.side = SIDE_Y
-				end
+				inp.side = (dx > dy) and const.SIDE.X or const.SIDE.Y
+
 				-- Check scroll side if we can scroll
-				if (self.can_x and inp.side == SIDE_X or
-					self.can_y and inp.side == SIDE_Y) then
+				if (self.can_x and inp.side == const.SIDE.X or
+					self.can_y and inp.side == const.SIDE.Y) then
 						M.current_scroll = self
 				end
 			end
@@ -308,6 +303,7 @@ function M.on_input(self, action_id, action)
 			M.current_scroll = nil
 			result = true
 		end
+
 		check_threshold(self)
 	end
 
@@ -316,6 +312,7 @@ end
 
 
 --- Start scroll to target point
+-- @function scroll:scroll_to
 -- @tparam point vector3 target point
 -- @tparam[opt] bool is_instant instant scroll flag
 -- @usage scroll:scroll_to(vmath.vector3(0, 50, 0))
@@ -343,7 +340,11 @@ function M.scroll_to(self, point, is_instant)
 end
 
 
---- Scroll to item in scroll by points index
+--- Scroll to item in scroll by point index
+-- @function scroll:init
+-- @tparam table self Component instance
+-- @tparam number index Point index
+-- @tparam[opt] boolean skip_cb If true, skip the point callback
 function M.scroll_to_index(self, index, skip_cb)
 	index = helper.clamp(index, 1, #self.points)
 
@@ -359,8 +360,11 @@ function M.scroll_to_index(self, index, skip_cb)
 end
 
 
---- Set points of interest
+--- Set points of interest.
 -- Scroll will always centered on closer points
+-- @function scroll:set_points
+-- @tparam table self Component instance
+-- @tparam table points Array of vector3 points
 function M.set_points(self, points)
 	self.points = points
 	-- cause of parent move in other side by y
@@ -375,21 +379,30 @@ function M.set_points(self, points)
 end
 
 
---- Enable or disable scroll inert
+--- Enable or disable scroll inert.
 -- If disabled, scroll through points (if exist)
 -- If no points, just simple drag without inertion
+-- @function scroll:set_inert
+-- @tparam table self Component instance
+-- @tparam boolean state Inert scroll state
 function M.set_inert(self, state)
 	self.is_inert = state
 end
 
 
 --- Set the callback on scrolling to point (if exist)
+-- @function scroll:on_point_move
+-- @tparam table self Component instance
+-- @tparam function callback Callback on scroll to point of interest
 function M.on_point_move(self, callback)
 	self.on_point_callback = callback
 end
 
 
 --- Set the scroll possibly area
+-- @function scroll:set_border
+-- @tparam table self Component instance
+-- @tparam vmath.vector3 border Size of scrolling area
 function M.set_border(self, border)
 	self.border = border
 

druid/base/text.lua

@@ -29,6 +29,10 @@ function M.init(self, node, value, is_locale, max_width)
 end
 
 
+--- Translate the text by locale_id
+-- @function text:translate
+-- @tparam table self Component instance
+-- @tparam string locale_id Locale id
 function M.translate(self, locale_id)
 	self.last_locale = locale_id or self.last_locale
 	self:set_to(settings.get_text(self.last_locale))
@@ -56,7 +60,9 @@ end
 
 
 --- Set text to text field
--- @param set_to - set value to text field
+-- @function text:set_to
+-- @tparam table self Component instance
+-- @tparam string set_to Text for node
 function M.set_to(self, set_to)
 	self.last_value = set_to
 	gui.set_text(self.node, set_to)
@@ -68,7 +74,9 @@ end
 
 
 --- Set color
--- @param color
+-- @function text:set_color
+-- @tparam table self Component instance
+-- @tparam vmath.vector4 color Color for node
 function M.set_color(self, color)
 	self.last_color = color
 	gui.set_color(self.node, color)
@@ -76,7 +84,9 @@ end
 
 
 --- Set alpha
--- @param alpha, number [0-1]
+-- @function text:set_alpha
+-- @tparam table self Component instance
+-- @tparam number alpha Alpha for node
 function M.set_alpha(self, alpha)
 	self.last_color.w = alpha
 	gui.set_color(self.node, self.last_color)
@@ -84,7 +94,9 @@ end
 
 
 --- Set scale
--- @param scale
+-- @function text:set_scale
+-- @tparam table self Component instance
+-- @tparam vmath.vector3 scale Scale for node
 function M.set_scale(self, scale)
 	self.last_scale = scale
 	gui.set_scale(self.node, scale)

druid/base/timer.lua

@@ -32,7 +32,9 @@ end
 
 
 --- Set text to text field
--- @param set_to - set value in seconds
+-- @function timer:set_to
+-- @tparam table self Component instance
+-- @tparam number set_to Value in seconds
 function M.set_to(self, set_to)
 	self.last_value = set_to
 	gui.set_text(self.node, formats.second_string_min(set_to))
@@ -40,15 +42,19 @@ end
 
 
 --- Called when update
--- @param is_on - boolean is timer on
+-- @function timer:set_state
+-- @tparam table self Component instance
+-- @tparam boolean is_on Timer enable state
 function M.set_state(self, is_on)
 	self.is_on = is_on
 end
 
 
 --- Set time interval
--- @param from - "from" time in seconds
--- @param to - "to" time in seconds
+-- @function timer:set_interval
+-- @tparam table self Component instance
+-- @tparam number from Start time in seconds
+-- @tparam number to Target time in seconds
 function M.set_interval(self, from, to)
 	self.from = from
 	self.value = from
@@ -59,8 +65,6 @@ function M.set_interval(self, from, to)
 end
 
 
---- Called when update
--- @param dt - delta time
 function M.update(self, dt)
 	if self.is_on then
 		self.temp = self.temp + dt

druid/const.lua

@@ -13,6 +13,7 @@ M.ACTION_BACK = hash("back")
 M.RELEASED = "released"
 M.PRESSED = "pressed"
 M.STRING = "string"
+M.ZERO = "0"
 
 --- Interests
 M.ON_MESSAGE = hash("on_message")
@@ -34,7 +35,12 @@ M.PIVOTS = {
 	[gui.PIVOT_NW] = vmath.vector3(-0.5, -0.5, 0),
 }
 
-M.ui_input = {
+M.SIDE = {
+	X = "x",
+	Y = "y"
+}
+
+M.UI_INPUT = {
 	[M.ON_SWIPE] = true,
 	[M.ON_INPUT] = true
 }

druid/helper/formats.lua

@@ -1,25 +1,27 @@
 --- Druid module with utils on string formats
 -- @module helper.formats
 
+local const = require("druid.const")
+
 local M = {}
 
-local ZERO = "0"
-
 --- Return number with zero number prefix
--- @param num number for conversion
--- @param count count of numerals
+-- @function formats.add_prefix_zeros
+-- @tparam number num Number for conversion
+-- @tparam number count Count of numerals
 -- @return string with need count of zero (1,3) -> 001
 function M.add_prefix_zeros(num, count)
 	local result = tostring(num)
 	for i = string.len(result), count - 1 do
-		result = ZERO..result
+		result = const.ZERO..result
 	end
 	return result
 end
 
 
 --- Convert seconds to string minutes:seconds
--- @param num number of seconds
+-- @function formats.second_string_min
+-- @tparam number sec Seconds
 -- @return string minutes:seconds
 function M.second_string_min(sec)
 	local mins = math.floor(sec / 60)
@@ -29,8 +31,9 @@ end
 
 
 --- Interpolate string with named Parameters in Table
--- @param s string for interpolate
--- @param tab table with parameters
+-- @function formats.second_string_min
+-- @tparam string s Target string
+-- @tparam table tab Table with parameters
 -- @return string with replaced parameters
 function M.interpolate_string(s, tab)
 	return (s:gsub('($%b{})', function(w) return tab[w:sub(3, -2)] or w end))

druid/rich/progress_rich.lua

@@ -1,51 +1,67 @@
+--- Component for rich progress component
+-- @module rich.progress_rich
+
 local settings = require("druid.settings")
 local pr_settings = settings.progress_rich
 
 local M = {}
 
-function M.init(instance, name, red, green, key)
-	instance.red = instance.parent:new_progress(red, key)
-	instance.green = instance.parent:new_progress(green, key)
-	instance.fill = instance.parent:new_progress(name, key)
+
+function M.init(self, name, red, green, key)
+	self.red = self.parent:new_progress(red, key)
+	self.green = self.parent:new_progress(green, key)
+	self.fill = self.parent:new_progress(name, key)
 end
 
 
-function M.set_to(instance, value)
-	instance.red:set_to(value)
-	instance.green:set_to(value)
-	instance.fill:set_to(value)
+--- Instant fill progress bar to value
+-- @function progress_rich:set_to
+-- @tparam table self Component instance
+-- @tparam number value Progress bar value, from 0 to 1
+function M.set_to(self, value)
+	self.red:set_to(value)
+	self.green:set_to(value)
+	self.fill:set_to(value)
 end
 
 
-function M.empty(instance)
-	instance.red:empty()
-	instance.green:empty()
-	instance.fill:empty()
+--- Empty a progress bar
+-- @function progress_rich:empty
+-- @tparam table self Component instance
+function M.empty(self)
+	self.red:empty()
+	self.green:empty()
+	self.fill:empty()
 end
 
 
-function M.to(instance, to, callback)
-	if instance.timer then
-		timer.cancel(instance.timer)
-		instance.timer = nil
+--- Start animation of a progress bar
+-- @function progress_rich:to
+-- @tparam table self Component instance
+-- @tparam number to value between 0..1
+-- @tparam[opt] function callback Callback on animation ends
+function M.to(self, to, callback)
+	if self.timer then
+		timer.cancel(self.timer)
+		self.timer = nil
 	end
 
-	if instance.fill.last_value < to then
-		instance.red:to(instance.fill.last_value)
-		instance.green:to(to, function()
-			instance.timer = timer.delay(pr_settings.DELAY, false, function()
-				instance.red:to(to)
-				instance.fill:to(to, callback)
+	if self.fill.last_value < to then
+		self.red:to(self.fill.last_value)
+		self.green:to(to, function()
+			self.timer = timer.delay(pr_settings.DELAY, false, function()
+				self.red:to(to)
+				self.fill:to(to, callback)
 			end)
 		end)
 	end
 
-	if instance.fill.last_value > to then
-		instance.green:to(instance.red.last_value)
-		instance.fill:to(to, function()
-			instance.timer = timer.delay(pr_settings.DELAY, false, function()
-				instance.green:to(to)
-				instance.red:to(to, callback)
+	if self.fill.last_value > to then
+		self.green:to(self.red.last_value)
+		self.fill:to(to, function()
+			self.timer = timer.delay(pr_settings.DELAY, false, function()
+				self.green:to(to)
+				self.red:to(to, callback)
 			end)
 		end)
 	end