update comments

10 files changed, 459 insertions, 65 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)
 
diff --git a/xmake/core/package/package.lua b/xmake/core/package/package.lua
index 6b725c404..1107e03b0 100644
--- a/xmake/core/package/package.lua
+++ b/xmake/core/package/package.lua
@@ -94,6 +94,9 @@ function _instance:memcache()
 end
 
 -- get the package name without namespace
+--
+-- @return      the package name string
+--
 function _instance:name()
     return self._NAME
 end
@@ -129,7 +132,11 @@ function _instance:base()
     return self._BASE
 end
 
--- get the package configuration
+-- get the package configuration value
+--
+-- @param name  the config name
+-- @return      the config value
+--
 function _instance:get(name)
     local value = self._INFO:get(name)
     if name == "configs" then
@@ -149,6 +156,10 @@ function _instance:get(name)
 end
 
 -- set the value to the package info
+--
+-- @param name  the info name
+-- @param ...   the values
+--
 function _instance:set(name, ...)
     if self._SOURCE_INITED then
         -- we can use set/add to modify urls, .. in on_load() if urls have been inited.
@@ -202,7 +213,10 @@ function _instance:description()
     return self:get("description")
 end
 
--- get the platform of package
+-- get the platform of package, e.g. "windows", "linux", "macosx"
+--
+-- @return      the platform name
+--
 function _instance:plat()
     if self._PLAT then
         return self._PLAT
@@ -217,7 +231,10 @@ function _instance:plat()
     return package.targetplat()
 end
 
--- get the architecture of package
+-- get the architecture of package, e.g. "x86_64", "arm64"
+--
+-- @return      the architecture name
+--
 function _instance:arch()
     if self._ARCH then
         return self._ARCH
@@ -266,7 +283,11 @@ function _instance:repo()
     return self._REPO
 end
 
--- the current platform is belong to the given platforms?
+-- is the package platform belong to the given platforms?
+--
+-- @param ...   the platform names
+-- @return      true if matched
+--
 function _instance:is_plat(...)
     local plat = self:plat()
     for _, v in ipairs(table.pack(...)) do
@@ -276,7 +297,11 @@ function _instance:is_plat(...)
     end
 end
 
--- the current architecture is belong to the given architectures?
+-- is the package architecture belong to the given architectures?
+--
+-- @param ...   the architecture names
+-- @return      true if matched
+--
 function _instance:is_arch(...)
     local arch = self:arch()
     for _, v in ipairs(table.pack(...)) do
@@ -325,7 +350,10 @@ function _instance:extsources()
     return self:get("extsources")
 end
 
--- get urls
+-- get the source urls
+--
+-- @return      the urls array
+--
 function _instance:urls()
     return self:current_scheme():urls()
 end
@@ -570,6 +598,9 @@ function _instance:kind()
 end
 
 -- is binary package?
+--
+-- @return      true if the package kind is "binary"
+--
 function _instance:is_binary()
     return self:kind() == "binary" or self:kind() == "toolchain"
 end
@@ -580,6 +611,9 @@ function _instance:is_toolchain()
 end
 
 -- is library package?
+--
+-- @return      true if the package kind is "library" or default
+--
 function _instance:is_library()
     return self:kind() == nil or self:kind() == "library"
 end
@@ -589,7 +623,10 @@ function _instance:is_template()
     return self:kind() == "template"
 end
 
--- is header only?
+-- is header-only library?
+--
+-- @return      true if the package kind is "headeronly"
+--
 function _instance:is_headeronly()
     return self:is_library() and self:extraconf("kind", "library", "headeronly")
 end
@@ -790,11 +827,17 @@ function _instance:unlock()
 end
 
 -- get the source directory
+--
+-- @return      the source directory path
+--
 function _instance:sourcedir()
     return self:get("sourcedir")
 end
 
 -- get the build directory
+--
+-- @return      the build directory path
+--
 function _instance:builddir()
     local builddir = self._BUILDDIR
     if not builddir then
@@ -817,6 +860,9 @@ function _instance:buildir()
 end
 
 -- get the cached directory of this package
+--
+-- @return      the cache directory path
+--
 function _instance:cachedir()
     local cachedir = self._CACHEDIR
     if not cachedir then
@@ -851,6 +897,10 @@ function _instance:cachedir()
 end
 
 -- get the installed directory of this package
+--
+-- @param ...   the subdirectory components (optional)
+-- @return      the install directory path
+--
 function _instance:installdir(...)
     local installdir = self._INSTALLDIR
     if not installdir then
diff --git a/xmake/core/project/target.lua b/xmake/core/project/target.lua
index aa204a054..1c568de65 100644
--- a/xmake/core/project/target.lua
+++ b/xmake/core/project/target.lua
@@ -718,12 +718,20 @@ function _instance:get_from(name, sources, opt)
 end
 
 -- set the value to the target info
+--
+-- @param name  the info name
+-- @param ...   the values
+--
 function _instance:set(name, ...)
     self._INFO:apival_set(name, ...)
     self:_invalidate(name)
 end
 
 -- add the value to the target info
+--
+-- @param name  the info name
+-- @param ...   the values to add
+--
 function _instance:add(name, ...)
     self._INFO:apival_add(name, ...)
     self:_invalidate(name)
@@ -825,11 +833,19 @@ function _instance:sourceinfo(name, item)
 end
 
 -- get user private data
+--
+-- @param name  the data key
+-- @return      the data value
+--
 function _instance:data(name)
     return self._DATA and self._DATA[name]
 end
 
 -- set user private data
+--
+-- @param name  the data key
+-- @param data  the data value
+--
 function _instance:data_set(name, data)
     self._DATA = self._DATA or {}
     self._DATA[name] = data
@@ -841,7 +857,12 @@ function _instance:data_add(name, data)
     self._DATA[name] = table.unwrap(table.join(self._DATA[name] or {}, data))
 end
 
--- get values
+-- get values set by set_values/add_values
+--
+-- @param name       the values name, e.g. "csharp.target_framework"
+-- @param sourcefile the source file (optional, for file-level values)
+-- @return          the values
+--
 function _instance:values(name, sourcefile)
 
     -- get values from the source file first
@@ -892,6 +913,9 @@ function _instance:type()
 end
 
 -- get the target name
+--
+-- @return      the target name string
+--
 function _instance:name()
     return self._NAME
 end
@@ -917,7 +941,10 @@ function _instance:fullname()
     return namespace and namespace .. "::" .. self:name() or self:name()
 end
 
--- get the target kind
+-- get the target kind, e.g. "binary", "shared", "static", "object", "headeronly"
+--
+-- @return      the kind string
+--
 function _instance:kind()
     return self:get("kind") or "binary"
 end
@@ -927,17 +954,27 @@ function _instance:targetkind()
     return self:kind()
 end
 
--- get the platform of this target
+-- get the platform of this target, e.g. "windows", "linux", "macosx"
+--
+-- @return      the platform name
+--
 function _instance:plat()
     return self:get("plat") or config.get("plat") or os.host()
 end
 
--- get the architecture of this target
+-- get the architecture of this target, e.g. "x86_64", "arm64"
+--
+-- @return      the architecture name
+--
 function _instance:arch()
     return self:get("arch") or config.get("arch") or os.arch()
 end
 
--- the current target is belong to the given platforms?
+-- is the current target belong to the given platforms?
+--
+-- @param ...   the platform names, e.g. "windows", "linux"
+-- @return      true if matched
+--
 function _instance:is_plat(...)
     local plat = self:plat()
     for _, v in ipairs(table.pack(...)) do
@@ -947,7 +984,11 @@ function _instance:is_plat(...)
     end
 end
 
--- the current target is belong to the given architectures?
+-- is the current target belong to the given architectures?
+--
+-- @param ...   the architecture names, e.g. "x86_64", "arm64"
+-- @return      true if matched
+--
 function _instance:is_arch(...)
     local arch = self:arch()
     for _, v in ipairs(table.pack(...)) do
@@ -1061,6 +1102,9 @@ function _instance:policy(name)
 end
 
 -- get the base name of target file
+--
+-- @return      the base name without extension
+--
 function _instance:basename()
     local filename = self:get("filename")
     if filename then
@@ -1116,6 +1160,10 @@ function _instance:linkflags()
 end
 
 -- get the given dependent target
+--
+-- @param name  the dependent target name
+-- @return      the target instance, or nil if not found
+--
 function _instance:dep(name)
     local deps = self:deps()
     if deps then
@@ -1130,7 +1178,10 @@ function _instance:dep(name)
     end
 end
 
--- get target deps
+-- get all dependent targets
+--
+-- @return      the deps table {name = target, ...}
+--
 function _instance:deps()
     if not self:_is_loaded() then
         os.raise("please call target:deps() or target:dep() in after_load()!")
@@ -1141,7 +1192,11 @@ function _instance:deps()
     return self._DEPS
 end
 
--- get target ordered deps
+-- get dependent targets in dependency order
+--
+-- @param opt   the options, e.g. {inherit = true}
+-- @return      the ordered deps array
+--
 function _instance:orderdeps(opt)
     opt = opt or {}
     if not self:_is_loaded() then
@@ -1170,6 +1225,10 @@ function _instance:orderules()
 end
 
 -- get target rule from the given rule name
+--
+-- @param name  the rule name
+-- @return      the rule instance, or nil if not found
+--
 function _instance:rule(name)
     if self._RULES then
         local r = self._RULES[name]
@@ -1213,26 +1272,41 @@ function _instance:is_phony()
 end
 
 -- is binary target?
+--
+-- @return      true if the target kind is "binary"
+--
 function _instance:is_binary()
     return self:kind() == "binary"
 end
 
 -- is shared library target?
+--
+-- @return      true if the target kind is "shared"
+--
 function _instance:is_shared()
     return self:kind() == "shared"
 end
 
 -- is static library target?
+--
+-- @return      true if the target kind is "static"
+--
 function _instance:is_static()
     return self:kind() == "static"
 end
 
 -- is object files target?
+--
+-- @return      true if the target kind is "object"
+--
 function _instance:is_object()
     return self:kind() == "object"
 end
 
 -- is headeronly target?
+--
+-- @return      true if the target kind is "headeronly"
+--
 function _instance:is_headeronly()
     return self:kind() == "headeronly"
 end
@@ -1323,12 +1397,21 @@ function _instance:orderopts(opt)
     return orderopts
 end
 
--- get the enabled package
+-- get the enabled package by name
+--
+-- @param name  the package name
+-- @param opt   the options (optional)
+-- @return      the package instance, or nil if not found
+--
 function _instance:pkg(name, opt)
     return self:pkgs(opt)[name]
 end
 
--- get the enabled packages
+-- get all enabled packages
+--
+-- @param opt   the options (optional)
+-- @return      the packages table {name = package, ...}
+--
 function _instance:pkgs(opt)
     opt = opt or {}
     local cachekey = "pkgs"
@@ -1348,7 +1431,11 @@ function _instance:pkgs(opt)
     return packages
 end
 
--- get the required packages with {interface|public = ..}
+-- get the required packages in order
+--
+-- @param opt   the options (optional)
+-- @return      the ordered packages array
+--
 function _instance:orderpkgs(opt)
     opt = opt or {}
     local cachekey = "orderpkgs"
@@ -1436,6 +1523,10 @@ function _instance:pkgconfig(pkgname)
 end
 
 -- get the object files directory
+--
+-- @param opt   the options (optional)
+-- @return      the object directory path
+--
 function _instance:objectdir(opt)
 
     -- the object directory
@@ -1509,7 +1600,11 @@ function _instance:dependir(opt)
     return dependir
 end
 
--- get the autogen files directory
+-- get the auto-generated files directory
+--
+-- @param opt   the options (optional)
+-- @return      the autogen directory path
+--
 function _instance:autogendir(opt)
 
     -- init the autogen directory
@@ -1623,7 +1718,10 @@ function _instance:_default_targetdir()
     return targetdir
 end
 
--- get the target directory
+-- get the target output directory
+--
+-- @return      the target directory path
+--
 function _instance:targetdir()
     local targetdir = self:get("targetdir")
     if not targetdir then
@@ -1674,7 +1772,10 @@ function _instance:artifactfile(kind)
     end
 end
 
--- get the target file name
+-- get the target file name (with prefix, extension)
+--
+-- @return      the file name string, e.g. "libfoo.a", "foo.exe"
+--
 function _instance:filename()
 
     -- no target file?
@@ -1699,7 +1800,10 @@ function _instance:filename()
     return filename
 end
 
--- get the link name only for static/shared library
+-- get the link name for static/shared library
+--
+-- @return      the link name string, e.g. "foo" for libfoo.a
+--
 function _instance:linkname()
     if self:is_static() or self:is_shared() then
         local filename = self:get("filename")
@@ -1716,7 +1820,10 @@ function _instance:linkname()
     end
 end
 
--- get the target file
+-- get the target file full path
+--
+-- @return      the target file path
+--
 function _instance:targetfile()
     local filename = self:filename()
     if filename then
@@ -1766,6 +1873,9 @@ function _instance:prefixdir()
 end
 
 -- get the installed binary directory
+--
+-- @return      the binary install directory path
+--
 function _instance:bindir()
     local bindir = baseoption.get("bindir")
     if bindir then
@@ -1779,6 +1889,9 @@ function _instance:bindir()
 end
 
 -- get the installed library directory
+--
+-- @return      the library install directory path
+--
 function _instance:libdir()
     local libdir = baseoption.get("libdir")
     if libdir then
@@ -1804,7 +1917,11 @@ function _instance:includedir()
     return self:installdir(includedir)
 end
 
--- get install directory
+-- get the install directory
+--
+-- @param ...   the subdirectory components (optional)
+-- @return      the install directory path
+--
 function _instance:installdir(...)
     opt = opt or {}
     local installdir = baseoption.get("installdir")
@@ -2005,6 +2122,9 @@ function _instance:fileconfig_add(sourcefile, info, opt)
 end
 
 -- get the source files
+--
+-- @return      the source files array
+--
 function _instance:sourcefiles()
 
     -- cached? return it directly
@@ -2113,7 +2233,11 @@ function _instance:sourcefiles()
     return sourcefiles, true
 end
 
--- get object file from source file
+-- get the object file path from source file
+--
+-- @param sourcefile  the source file path
+-- @return          the object file path
+--
 function _instance:objectfile(sourcefile)
     return self:autogenfile(sourcefile, {rootdir = self:objectdir(),
         filename = target.filename(path.filename(sourcefile), "object", {
@@ -2122,7 +2246,10 @@ function _instance:objectfile(sourcefile)
             format = self:_format("object")})})
 end
 
--- get the object files
+-- get all object files
+--
+-- @return      the object files array
+--
 function _instance:objectfiles()
 
     -- get source batches
@@ -2366,7 +2493,10 @@ function _instance:sourcecount()
     return #self:sourcefiles()
 end
 
--- get source batches
+-- get source batches grouped by source kind
+--
+-- @return      the source batches table {sourcekind = {sourcefiles = {...}, ...}, ...}
+--
 function _instance:sourcebatches()
 
     -- get source files
@@ -2568,7 +2698,11 @@ function _instance:has_runtime(...)
     end
 end
 
--- get the given toolchain
+-- get the given toolchain by name
+--
+-- @param name  the toolchain name, e.g. "gcc", "clang", "msvc"
+-- @return      the toolchain instance, or nil if not found
+--
 function _instance:toolchain(name)
     local toolchains_map = self:memcache():get("toolchains_map")
     if toolchains_map == nil then
@@ -2581,7 +2715,10 @@ function _instance:toolchain(name)
     return toolchains_map[name]
 end
 
--- get the toolchains
+-- get all toolchains of this target
+--
+-- @return      the toolchains array
+--
 function _instance:toolchains()
     local toolchains = self:memcache():get("toolchains")
     if toolchains == nil then
@@ -2633,6 +2770,10 @@ function _instance:toolchains()
 end
 
 -- get the program and name of the given tool kind
+--
+-- @param toolkind   the tool kind, e.g. "cc", "cxx", "ld", "sh", "ar"
+-- @return          the program path, the tool name
+--
 function _instance:tool(toolkind)
     -- we cannot get tool in on_load, because target:toolchains() has been not checked in configuration stage.
     if not self._LOADED_AFTER then
diff --git a/xmake/core/tool/toolchain.lua b/xmake/core/tool/toolchain.lua
index 5ca360492..1491f34f3 100644
--- a/xmake/core/tool/toolchain.lua
+++ b/xmake/core/tool/toolchain.lua
@@ -79,6 +79,9 @@ function _instance.new(name, info, opt)
 end
 
 -- get toolchain name
+--
+-- @return      the toolchain name string
+--
 function _instance:name()
     return self._NAME
 end
@@ -109,7 +112,10 @@ function _instance:memcache()
     return cache
 end
 
--- get toolchain platform
+-- get toolchain platform, e.g. "windows", "linux", "macosx"
+--
+-- @return      the platform name
+--
 function _instance:plat()
     return self._PLAT or self:config("plat")
 end
@@ -119,7 +125,10 @@ function _instance:plat_set(plat)
     self._PLAT = plat
 end
 
--- get toolchain architecture
+-- get toolchain architecture, e.g. "x86_64", "arm64"
+--
+-- @return      the architecture name
+--
 function _instance:arch()
     return self._ARCH or self:config("arch")
 end
@@ -234,6 +243,9 @@ function _instance:is_builtin()
 end
 
 -- get the run environments
+--
+-- @return      the run environments table {PATH = "...", ...}
+--
 function _instance:runenvs()
     local runenvs = self._RUNENVS
     if runenvs == nil then
@@ -254,6 +266,10 @@ function _instance:runenvs()
 end
 
 -- get the program and name of the given tool kind
+--
+-- @param toolkind   the tool kind, e.g. "cc", "cxx", "ld", "ar"
+-- @return          the program path, the tool name
+--
 function _instance:tool(toolkind)
     if not self:_is_checked() then
         utils.warning("we cannot get tool(%s) in toolchain(%s) with %s/%s, because it has been not checked yet!", toolkind, self:name(), self:plat(), self:arch())
@@ -282,7 +298,10 @@ function _instance:cross()
     return self:config("cross") or config.get("cross") or self:info():get("cross")
 end
 
--- get the bin directory
+-- get the toolchain bin directory
+--
+-- @return      the bin directory path
+--
 function _instance:bindir()
     local bindir = self:config("bindir") or config.get("bin") or self:info():get("bindir")
     if not bindir and self:sdkdir() and os.isdir(path.join(self:sdkdir(), "bin")) then
@@ -291,7 +310,10 @@ function _instance:bindir()
     return bindir
 end
 
--- get the sdk directory
+-- get the toolchain sdk directory
+--
+-- @return      the sdk directory path
+--
 function _instance:sdkdir()
     return self:config("sdkdir") or config.get("sdk") or self:info():get("sdkdir")
 end
@@ -301,12 +323,20 @@ function _instance:cachekey()
     return self._CACHEKEY
 end
 
--- get user config from `set_toolchains("", {configs = {vs = "2018"}})`
+-- get toolchain config value
+--
+-- @param name  the config name, e.g. "sdkver", "vs"
+-- @return      the config value
+--
 function _instance:config(name)
     return self._CONFIGS[name]
 end
 
--- set user config
+-- set toolchain config value
+--
+-- @param name  the config name
+-- @param data  the config value
+--
 function _instance:config_set(name, data)
     self._CONFIGS[name] = data
 end
@@ -317,6 +347,9 @@ function _instance:configs_save()
 end
 
 -- do check, we only check it once for all architectures
+--
+-- @return      true if the toolchain is available
+--
 function _instance:check()
     local checked = self:config("__checked")
     if checked == nil then