update comments

7 files changed, 200 insertions, 30 deletions

diff --git a/xmake/core/base/option.lua b/xmake/core/base/option.lua
index 6d46bddef..decb1e842 100644
--- a/xmake/core/base/option.lua
+++ b/xmake/core/base/option.lua
@@ -65,7 +65,11 @@ function option._context()
     end
 end
 
--- save context
+-- save option context (push a new context onto the stack)
+--
+-- @param taskname   the task name (optional)
+-- @return          the new context
+--
 function option.save(taskname)
     option._CONTEXTS = option._CONTEXTS or {}
     local context = {options = {}, defaults = {}, taskname = taskname}
@@ -76,7 +80,7 @@ function option.save(taskname)
     return context
 end
 
--- restore context
+-- restore option context (pop the current context from the stack)
 function option.restore()
     if option._CONTEXTS then
         table.remove(option._CONTEXTS)
@@ -142,7 +146,13 @@ function option.init(menu)
     return true
 end
 
--- parse arguments with the given options
+-- parse arguments with the given options definition
+--
+-- @param argv      the arguments array or string
+-- @param options   the options definition table
+-- @param opt       the description and usage strings
+-- @return          the parsed options table
+--
 function option.parse(argv, options, opt)
     assert(argv and options)
     opt = opt or { populate_defaults = true }
@@ -306,6 +316,9 @@ end
 
 
 -- get the current task name
+--
+-- @return      the task name string
+--
 function option.taskname()
     return option._context().taskname
 end
@@ -324,6 +337,10 @@ function option.taskmenu(task)
 end
 
 -- get the given option value for the current task
+--
+-- @param name  the option name, e.g. "verbose", "diagnosis", "target"
+-- @return      the option value
+--
 function option.get(name)
     local options = option.options()
     if options then
@@ -336,6 +353,10 @@ function option.get(name)
 end
 
 -- set the given option for the current task
+--
+-- @param name  the option name
+-- @param value the option value
+--
 function option.set(name, value)
     -- cannot be the first context for menu
     assert(#option._CONTEXTS > 1)
@@ -348,7 +369,11 @@ function option.set(name, value)
     options[name] = value
 end
 
--- get the boolean value
+-- convert value to boolean (handles "y", "yes", "true", etc.)
+--
+-- @param value the value to convert
+-- @return      true, false, or nil
+--
 function option.boolean(value)
     if type(value) == "string" then
         local v = value:lower()
@@ -359,7 +384,11 @@ function option.boolean(value)
     return value
 end
 
--- get the given default option value for the current task
+-- get the default option value for the current task
+--
+-- @param name  the option name
+-- @return      the default value
+--
 function option.default(name)
     assert(name)
 
diff --git a/xmake/core/base/pipe.lua b/xmake/core/base/pipe.lua
index 4b122ed9e..137f9c779 100644
--- a/xmake/core/base/pipe.lua
+++ b/xmake/core/base/pipe.lua
@@ -59,6 +59,11 @@ function _instance:cdata()
 end
 
 -- write data to pipe file
+--
+-- @param data  the data to write (string or bytes)
+-- @param opt   the options, e.g. {block = true}
+-- @return      the real written size, or -1 and error info
+--
 function _instance:write(data, opt)
 
     -- ensure opened
@@ -119,6 +124,12 @@ function _instance:write(data, opt)
 end
 
 -- read data from pipe
+--
+-- @param buff  the buffer to receive data
+-- @param size  the read size
+-- @param opt   the options, e.g. {block = true}
+-- @return      the real read size, or -1 and error info
+--
 function _instance:read(buff, size, opt)
     assert(buff)
 
@@ -187,6 +198,10 @@ function _instance:read(buff, size, opt)
 end
 
 -- connect pipe, only for named pipe (server-side)
+--
+-- @param opt   the options
+-- @return      true on success
+--
 function _instance:connect(opt)
 
     -- ensure opened
@@ -218,6 +233,11 @@ function _instance:connect(opt)
 end
 
 -- wait pipe events
+--
+-- @param events    the events to wait, e.g. pipe.EV_READ, pipe.EV_WRITE
+-- @param timeout   the timeout in milliseconds, -1 for infinite
+-- @return          the received events, or 0 on timeout
+--
 function _instance:wait(events, timeout)
 
     -- ensure opened
@@ -241,6 +261,9 @@ function _instance:wait(events, timeout)
 end
 
 -- close pipe file
+--
+-- @return      true on success
+--
 function _instance:close()
 
     -- ensure opened
diff --git a/xmake/core/base/poller.lua b/xmake/core/base/poller.lua
index b989af8a9..bb18dfda4 100644
--- a/xmake/core/base/poller.lua
+++ b/xmake/core/base/poller.lua
@@ -56,17 +56,27 @@ function poller:_pollerdata_set(cdata, data)
     pollerdata[cdata] = data
 end
 
--- support events?
+-- check if the poller supports the given events
+--
+-- @param events    the events to check
+-- @return          true if supported
+--
 function poller:support(events)
     return io.poller_support(events)
 end
 
--- spank poller to break the wait() and return all triggered events
+-- spank the poller to break wait() and return immediately
 function poller:spank()
     io.poller_spank()
 end
 
 -- insert object events to poller
+--
+-- @param obj       the object (pipe, socket, process, fwatcher)
+-- @param events    the events to monitor
+-- @param udata     the user data (optional)
+-- @return          true on success, or false and error info
+--
 function poller:insert(obj, events, udata)
 
     -- insert it
@@ -81,6 +91,12 @@ function poller:insert(obj, events, udata)
 end
 
 -- modify object events in poller
+--
+-- @param obj       the object
+-- @param events    the new events to monitor
+-- @param udata     the user data (optional)
+-- @return          true on success, or false and error info
+--
 function poller:modify(obj, events, udata)
 
     -- modify it
@@ -95,6 +111,10 @@ function poller:modify(obj, events, udata)
 end
 
 -- remove object from poller
+--
+-- @param obj       the object to remove
+-- @return          true on success, or false and error info
+--
 function poller:remove(obj)
 
     -- remove it
@@ -108,7 +128,11 @@ function poller:remove(obj)
     return true
 end
 
--- wait object events in poller
+-- wait for object events in poller
+--
+-- @param timeout   the timeout in milliseconds, -1 for infinite
+-- @return          the number of events, or -1 on error
+--
 function poller:wait(timeout)
 
     -- wait it
diff --git a/xmake/core/base/process.lua b/xmake/core/base/process.lua
index 692a6360f..35b0b15b7 100644
--- a/xmake/core/base/process.lua
+++ b/xmake/core/base/process.lua
@@ -51,6 +51,9 @@ function _subprocess.new(program, proc)
 end
 
 -- get the process name
+--
+-- @return      the process name string
+--
 function _subprocess:name()
     if not self._NAME then
         self._NAME = path.filename(self:program())
@@ -58,7 +61,10 @@ function _subprocess:name()
     return self._NAME
 end
 
--- get the process program
+-- get the process program path
+--
+-- @return      the program path string
+--
 function _subprocess:program()
     return self._PROGRAM
 end
@@ -101,7 +107,10 @@ function _subprocess:wait(timeout)
     return result, status_or_errors
 end
 
--- kill subprocess
+-- kill the subprocess
+--
+-- @return      true on success
+--
 function _subprocess:kill()
 
     -- ensure opened
@@ -115,7 +124,10 @@ function _subprocess:kill()
     return true
 end
 
--- close subprocess
+-- close the subprocess and release resources
+--
+-- @return      true on success
+--
 function _subprocess:close()
 
     -- ensure opened
@@ -305,7 +317,12 @@ function process._get_missing_dlls(program)
     return missing
 end
 
--- get process exit errors
+-- get process exit error message
+--
+-- @param program    the program path
+-- @param exitcode   the exit code
+-- @return          the error message string, or nil
+--
 function process.get_exit_errors(program, exitcode)
     local errors
     if os.is_host("windows") then
diff --git a/xmake/core/base/task.lua b/xmake/core/base/task.lua
index 29cca38f2..27ad5023a 100644
--- a/xmake/core/base/task.lua
+++ b/xmake/core/base/task.lua
@@ -365,7 +365,12 @@ function task.apis()
     }
 end
 
--- new a task instance
+-- create a new task instance
+--
+-- @param name  the task name
+-- @param info  the task info table
+-- @return      the task instance
+--
 function task.new(name, info)
     local instance = table.inherit(task)
     if name then
@@ -380,7 +385,10 @@ function task.new(name, info)
     return instance
 end
 
--- get global tasks
+-- get all registered tasks
+--
+-- @return      the tasks table {name = task, ...}
+--
 function task.tasks()
     if task._TASKS then
         return task._TASKS
@@ -410,12 +418,20 @@ function task.tasks()
     return instances
 end
 
--- get the given global task
+-- get the given task by name
+--
+-- @param name  the task name
+-- @return      the task instance, or nil if not found
+--
 function task.task(name)
     return task.tasks()[name]
 end
 
--- get the task menu
+-- get the task menu for command line parsing
+--
+-- @param tasks the tasks table (optional, default all tasks)
+-- @return      the menu table
+--
 function task.menu(tasks)
     local menu = {}
     for taskname, taskinst in pairs(tasks) do
diff --git a/xmake/core/base/timer.lua b/xmake/core/base/timer.lua
index 98eef80a3..30f4bafb3 100644
--- a/xmake/core/base/timer.lua
+++ b/xmake/core/base/timer.lua
@@ -35,7 +35,13 @@ function timer:_tasks()
     return self._TASKS
 end
 
--- post timer task after delay and will be auto-remove it after be expired
+-- post a timer task after delay (auto-removed after expiration)
+--
+-- @param func  the callback function
+-- @param delay the delay in milliseconds
+-- @param opt   the options, e.g. {continuous = true}
+-- @return      the task handle (set task.cancel = true to cancel)
+--
 function timer:post(func, delay, opt)
     return self:post_at(func, os.mclock() + delay, delay, opt)
 end
@@ -51,12 +57,22 @@ function timer:post_at(func, when, period, opt)
     return task
 end
 
--- post timer task after the relative time and will be auto-remove it after be expired
+-- post a timer task after the relative time with optional repeat period
+--
+-- @param func    the callback function
+-- @param after   the initial delay in milliseconds
+-- @param period  the repeat period in milliseconds (0 for one-shot)
+-- @param opt     the options, e.g. {continuous = true}
+-- @return        the task handle
+--
 function timer:post_after(func, after, period, opt)
     return self:post_at(func, os.mclock() + after, period, opt)
 end
 
--- get the delay of next task
+-- get the delay until the next task fires
+--
+-- @return      the delay in milliseconds, or -1 if no tasks
+--
 function timer:delay()
     local delay = nil
     local tasks = self:_tasks()
@@ -70,7 +86,7 @@ function timer:delay()
     return delay
 end
 
--- run the timer next loop
+-- run the next timer loop, executing expired tasks
 function timer:next()
     local tasks = self:_tasks()
     while tasks:length() > 0 do
@@ -101,7 +117,7 @@ function timer:next()
     return true
 end
 
--- kill all timer tasks
+-- kill all pending timer tasks
 function timer:kill()
     local tasks = self:_tasks()
     while tasks:length() > 0 do
@@ -129,7 +145,11 @@ function timer:init(name)
     end}
 end
 
--- new timer
+-- create a new timer
+--
+-- @param name  the timer name for debugging
+-- @return      the timer instance
+--
 function timer:new(name)
     self = self()
     self:init(name)
diff --git a/xmake/core/base/utils.lua b/xmake/core/base/utils.lua
index ddf8c127f..771dc09f7 100644
--- a/xmake/core/base/utils.lua
+++ b/xmake/core/base/utils.lua
@@ -31,7 +31,10 @@ local dump   = require("base/dump")
 local text   = require("base/text")
 
 
--- dump values
+-- dump values with colored pretty-printing
+--
+-- @param ...   the values to dump
+--
 function utils.dump(...)
     if option.get("quiet") then
         return ...
@@ -142,6 +145,10 @@ function utils._decode_errors(errors)
 end
 
 -- print format string with newline
+--
+-- @param format the format string
+-- @param ...    the format arguments
+--
 function utils.print(format, ...)
     assert(format)
     local message = string.tryformat(format, ...)
@@ -150,6 +157,10 @@ function utils.print(format, ...)
 end
 
 -- print format string without newline
+--
+-- @param format the format string
+-- @param ...    the format arguments
+--
 function utils.printf(format, ...)
     assert(format)
     local message = string.tryformat(format, ...)
@@ -157,7 +168,11 @@ function utils.printf(format, ...)
     log:write(message)
 end
 
--- print format string and colors with newline
+-- print format string with color markup and newline
+--
+-- @param format the format string with ${color} markup
+-- @param ...    the format arguments
+--
 function utils.cprint(format, ...)
     assert(format)
     local message = string.tryformat(format, ...)
@@ -167,7 +182,11 @@ function utils.cprint(format, ...)
     end
 end
 
--- print format string and colors without newline
+-- print format string with color markup without newline
+--
+-- @param format the format string with ${color} markup
+-- @param ...    the format arguments
+--
 function utils.cprintf(format, ...)
     assert(format)
     local message = string.tryformat(format, ...)
@@ -177,7 +196,11 @@ function utils.cprintf(format, ...)
     end
 end
 
--- print the verbose information
+-- print the verbose information (only when -v is enabled)
+--
+-- @param format the format string
+-- @param ...    the format arguments
+--
 function utils.vprint(format, ...)
     if (option.get("verbose") or option.get("diagnosis")) and format ~= nil then
         utils.print(format, ...)
@@ -191,7 +214,11 @@ function utils.vprintf(format, ...)
     end
 end
 
--- print the diagnosis information
+-- print the diagnosis information (only when -D is enabled)
+--
+-- @param format the format string
+-- @param ...    the format arguments
+--
 function utils.dprint(format, ...)
     if option.get("diagnosis") and format ~= nil then
         utils.print(format, ...)
@@ -205,7 +232,11 @@ function utils.dprintf(format, ...)
     end
 end
 
--- print the error information
+-- print the error information to stderr
+--
+-- @param format the format string
+-- @param ...    the format arguments
+--
 function utils.error(format, ...)
     if format ~= nil then
         local errors = string.tryformat(format, ...)
@@ -218,7 +249,11 @@ function utils.error(format, ...)
     end
 end
 
--- add warning message
+-- add a warning message (displayed at the end of execution)
+--
+-- @param format the format string
+-- @param ...    the format arguments
+--
 function utils.warning(format, ...)
     if option.get("quiet") then
         return
@@ -253,7 +288,13 @@ function utils.show_warnings()
     end
 end
 
--- try to call script
+-- try to call script safely
+--
+-- @param script     the script function
+-- @param traceback  the traceback function (optional)
+-- @param ...        the script arguments
+-- @return           true and results on success, or false and errors
+--
 function utils.trycall(script, traceback, ...)
     return xpcall(script, function (errors)