From b72e7451e1814b0b278717d4ed1180cc6733b07e Mon Sep 17 00:00:00 2001
From: Insality <insality@gmail.com>
Date: Wed, 25 Sep 2019 20:40:41 +0300
Subject: [PATCH] Add example docs for LDoc

---
 druid/base/back_handler.lua    | 17 ++++++++++++-----
 druid/base/button.lua          |  7 +++++--
 druid/base/grid.lua            | 10 +++++-----
 druid/base/progress.lua        |  5 ++++-
 druid/base/scroll.lua          |  9 ++++++++-
 druid/base/text.lua            |  6 +++++-
 druid/base/timer.lua           |  4 ++++
 druid/data.lua                 | 13 ++++++++-----
 druid/druid.lua                | 12 +++++++++++-
 druid/helper.lua               |  3 +++
 druid/helper/druid_animate.lua |  3 +++
 druid/helper/druid_input.lua   |  4 ++++
 druid/helper/formats.lua       | 21 ++++++++++++---------
 druid/settings.lua             | 13 ++++++++-----
 14 files changed, 92 insertions(+), 35 deletions(-)

diff --git a/druid/base/back_handler.lua b/druid/base/back_handler.lua
index 775b01e..9afa864 100644
--- a/druid/base/back_handler.lua
+++ b/druid/base/back_handler.lua
@@ -1,3 +1,6 @@
+--- Component to handle back key
+-- @module base.back_handler
+
 local data = require("druid.data")
 
 local M = {}
@@ -5,21 +8,25 @@ M.interest = {
 	data.ON_INPUT
 }
 
-
+--- Component init function
+-- @tparam table self component instance
+-- @tparam callback callback on back button
+-- @tparam[opt] params callback argument
 function M.init(self, callback, params)
-	self.event = data.A_ANDR_BACK
+	self.event = data.ACTION_BACK
 	self.callback = callback
 	self.params = params
 end
 
 
---- input handler
--- @param action_id - input action id
--- @param action - input action
+--- Input handler for component
+-- @tparam string action_id on_input action id
+-- @tparam table action on_input action
 function M.on_input(self, action_id, action)
 	if action[data.RELEASED] then
 		self.callback(self.parent.parent, self.params)
 	end
+
 	return true
 end
 
diff --git a/druid/base/button.lua b/druid/base/button.lua
index f5bfab2..8015fb3 100644
--- a/druid/base/button.lua
+++ b/druid/base/button.lua
@@ -1,3 +1,6 @@
+--- Component to handle basic GUI button
+-- @module base.button
+
 local data = require("druid.data")
 local ui_animate = require("druid.helper.druid_animate")
 local settings = require("druid.settings")
@@ -17,7 +20,7 @@ M.DEFAUL_ACTIVATION_TIME = 0.2
 
 function M.init(self, node, callback, params, anim_node, event)
 	self.node = helper.get_node(node)
-	self.event = data.A_TOUCH
+	self.event = data.ACTION_TOUCH
 	self.anim_node = anim_node and helper.get_node(anim_node) or self.node
 	self.scale_from = gui.get_scale(self.anim_node)
 	self.scale_to = self.scale_from + b_settings.SCALE_CHANGE
@@ -185,4 +188,4 @@ function M.set_ext_zone(self, zone)
 end
 
 
-return M
\ No newline at end of file
+return M
diff --git a/druid/base/grid.lua b/druid/base/grid.lua
index 496aea3..acdfcbd 100644
--- a/druid/base/grid.lua
+++ b/druid/base/grid.lua
@@ -1,11 +1,11 @@
+--- Component to handle placing components by row and columns.
+-- Grid can anchor your elements, get content size and other
+-- @module base.grid
+
 local helper = require("druid.helper")
 
 local M = {}
 
---- Sort and placing nodes
--- Plans: placing by max width, placing with max in_row
--- Allow different node sizes, allow animation with node insert
-
 
 function M.init(self, parent, element, in_row)
 	self.parent = helper.get_node(parent)
@@ -111,4 +111,4 @@ function M.clear(self)
 end
 
 
-return M
\ No newline at end of file
+return M
diff --git a/druid/base/progress.lua b/druid/base/progress.lua
index 2df0663..e0d2b88 100644
--- a/druid/base/progress.lua
+++ b/druid/base/progress.lua
@@ -1,3 +1,6 @@
+--- Component to handle progress bars
+-- @module base.progress
+
 local data = require("druid.data")
 local helper = require("druid.helper")
 local settings = require("druid.settings")
@@ -147,4 +150,4 @@ function M.update(self, dt)
 end
 
 
-return M
\ No newline at end of file
+return M
diff --git a/druid/base/scroll.lua b/druid/base/scroll.lua
index 2c651a9..d561e5d 100644
--- a/druid/base/scroll.lua
+++ b/druid/base/scroll.lua
@@ -1,3 +1,6 @@
+--- Component to handle scroll content
+-- @module base.scroll
+
 local helper = require("druid.helper")
 local data = require("druid.data")
 local settings = require("druid.settings").scroll
@@ -310,7 +313,11 @@ function M.on_input(self, action_id, action)
 end
 
 
---- Start scroll to point (x, y, z)
+--- Start scroll to target point
+-- @tparam point vector3 target point
+-- @tparam[opt] bool is_instant instant scroll flag
+-- @usage scroll:scroll_to(vmath.vector3(0, 50, 0))
+-- @usage scroll:scroll_to(vmath.vector3(0), true)
 function M.scroll_to(self, point, is_instant)
 	local b = self.border
 	local target = vmath.vector3(point)
diff --git a/druid/base/text.lua b/druid/base/text.lua
index 63708b8..297ddc4 100644
--- a/druid/base/text.lua
+++ b/druid/base/text.lua
@@ -1,3 +1,7 @@
+--- Component to handle all GUI texts
+-- Good working with localization system
+-- @module base.text
+
 local data = require("druid.data")
 local settings = require("druid.settings")
 local helper = require("druid.helper")
@@ -81,4 +85,4 @@ function M.set_scale(self, scale)
 end
 
 
-return M
\ No newline at end of file
+return M
diff --git a/druid/base/timer.lua b/druid/base/timer.lua
index 73fb49e..801cc7e 100644
--- a/druid/base/timer.lua
+++ b/druid/base/timer.lua
@@ -1,3 +1,6 @@
+--- Component to handle GUI timers
+-- @module base.timer
+
 local data = require("druid.data")
 local formats = require("druid.helper.formats")
 local helper = require("druid.helper")
@@ -9,6 +12,7 @@ M.interest = {
 
 local empty = function() end
 
+
 function M.init(self, node, seconds_from, seconds_to, callback)
 	self.node = helper.get_node(node)
 	seconds_from = math.max(seconds_from, 0)
diff --git a/druid/data.lua b/druid/data.lua
index b169895..eb870dd 100644
--- a/druid/data.lua
+++ b/druid/data.lua
@@ -1,11 +1,14 @@
+--- Druid constants
+-- @module constants
+
 local M = {}
 
 -- Actions
-M.A_TOUCH = hash("touch")
-M.A_TEXT = hash("text")
-M.A_BACKSPACE = hash("backspace")
-M.A_ENTER = hash("enter")
-M.A_ANDR_BACK = hash("back")
+M.ACTION_TOUCH = hash("touch")
+M.ACTION_TEXT = hash("text")
+M.ACTION_BACKSPACE = hash("backspace")
+M.ACTION_ENTER = hash("enter")
+M.ACTION_BACK = hash("back")
 
 M.RELEASED = "released"
 M.PRESSED = "pressed"
diff --git a/druid/druid.lua b/druid/druid.lua
index 22b274a..f24a12e 100644
--- a/druid/druid.lua
+++ b/druid/druid.lua
@@ -1,3 +1,9 @@
+--- 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.
+-- @module druid
+
 local data = require("druid.data")
 local druid_input = require("druid.helper.druid_input")
 local settings = require("druid.settings")
@@ -7,6 +13,7 @@ local M = {}
 local log = settings.log
 local _fct_metatable = {}
 
+--- Basic components
 M.comps = {
 	button = require("druid.base.button"),
 	back_handler = require("druid.base.back_handler"),
@@ -31,6 +38,9 @@ local function register_basic_components()
 end
 
 
+--- Register external module
+-- @tparam string name module name
+-- @tparam table module lua table with module
 function M.register(name, module)
 	-- TODO: Find better solution to creating elements?
 	_fct_metatable["new_" .. name] = function(self, ...)
@@ -209,4 +219,4 @@ function _fct_metatable.update(self, dt)
 end
 
 
-return M
\ No newline at end of file
+return M
diff --git a/druid/helper.lua b/druid/helper.lua
index 7e36f75..d428eb5 100644
--- a/druid/helper.lua
+++ b/druid/helper.lua
@@ -1,3 +1,6 @@
+--- Druid helper module
+-- @module helper
+
 local M = {}
 
 --- Text node or icon node can be nil
diff --git a/druid/helper/druid_animate.lua b/druid/helper/druid_animate.lua
index 12828b4..fa58cc4 100644
--- a/druid/helper/druid_animate.lua
+++ b/druid/helper/druid_animate.lua
@@ -1,3 +1,6 @@
+--- Druid helper module for animating GUI nodes
+-- @module helper.animate
+
 local M = {}
 
 local PROP_SCALE = gui.PROP_SCALE
diff --git a/druid/helper/druid_input.lua b/druid/helper/druid_input.lua
index 89ca0af..6a447c8 100644
--- a/druid/helper/druid_input.lua
+++ b/druid/helper/druid_input.lua
@@ -1,3 +1,7 @@
+--- Druid inner module to acquire/release input
+-- @module helper.input
+-- @local
+
 local M = {}
 
 local ADD_FOCUS = hash("acquire_input_focus")
diff --git a/druid/helper/formats.lua b/druid/helper/formats.lua
index 040c274..96aa487 100644
--- a/druid/helper/formats.lua
+++ b/druid/helper/formats.lua
@@ -1,10 +1,13 @@
+--- Druid module with utils on string formats
+-- @module helper.formats
+
 local M = {}
 
 local ZERO = "0"
 
--- Return number with zero number prefix
--- @param num - number for conversion
--- @param count - count of numerals
+--- Return number with zero number prefix
+-- @param num number for conversion
+-- @param 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)
@@ -15,8 +18,8 @@ function M.add_prefix_zeros(num, count)
 end
 
 
--- Convert seconds to string minutes:seconds
--- @param num - number of seconds
+--- Convert seconds to string minutes:seconds
+-- @param num number of seconds
 -- @return string minutes:seconds
 function M.second_string_min(sec)
 	local mins = math.floor(sec / 60)
@@ -25,11 +28,11 @@ function M.second_string_min(sec)
 end
 
 
--- Interpolate string with named Parameters in Table
--- @param s - string for interpolate
--- @param tab - table with parameters
+--- Interpolate string with named Parameters in Table
+-- @param s string for interpolate
+-- @param tab table with parameters
 -- @return string with replaced parameters
-function M.interpolate_strinng(s, tab)
+function M.interpolate_string(s, tab)
 	return (s:gsub('($%b{})', function(w) return tab[w:sub(3, -2)] or w end))
 end
 
diff --git a/druid/settings.lua b/druid/settings.lua
index bd2b31c..d0b51d5 100644
--- a/druid/settings.lua
+++ b/druid/settings.lua
@@ -1,7 +1,10 @@
+--- Druid settings file
+-- @module settings
+
 local M = {}
 
+-- TODO: to JSON?
 M.is_debug = false
-
 M.button = {
 	IS_HOVER = true,
 	IS_HOLD = true,
@@ -33,13 +36,13 @@ M.scroll = {
 }
 
 function M.get_text(name)
-  -- override to get text for localized text
-  return "locales not inited"
+	-- override to get text for localized text
+	return "[Druid]: locales not inited"
 end
 
 
 function M.play_sound(name)
-  -- override to play sound with name
+	-- override to play sound with name
 end
 
 
@@ -50,4 +53,4 @@ function M.log(...)
 end
 
 
-return M
\ No newline at end of file
+return M