update more comments

3 files changed, 131 insertions, 37 deletions

diff --git a/xmake/modules/core/project/depend.lua b/xmake/modules/core/project/depend.lua
index 71e50a56a..511e6fde6 100644
--- a/xmake/modules/core/project/depend.lua
+++ b/xmake/modules/core/project/depend.lua
@@ -96,11 +96,21 @@ function save(dependinfo, dependfile)
     io.save(dependfile, dependinfo)
 end
 
--- Is the dependent info changed?
+-- is the dependent info changed?
 --
--- if not depend.is_changed(dependinfo, {filemtime = os.mtime(objectfile), values = {...}}) then
+-- @param dependinfo    the depend info table from depend.load()
+-- @param opt           the options
+--                      - lastmtime: the last modification time to compare
+--                      - values: the depend values to compare
+--                      - files: the depend files (optional, from dependinfo.files)
+--                      - timecache: enable time cache for performance (optional)
+-- @return              true if changed
+--
+-- @code
+-- if not depend.is_changed(dependinfo, {lastmtime = os.mtime(objectfile), values = {program, flags}}) then
 --      return
 -- end
+-- @endcode
 --
 function is_changed(dependinfo, opt)
 
@@ -185,23 +195,21 @@ function is_changed(dependinfo, opt)
     end
 end
 
--- on changed for the dependent files and values
+-- run callback only when dependent files or values have changed
 --
--- e.g.
+-- @param callback      the callback function to run when changed
+-- @param opt           the options
+--                      - dependfile: the depend cache file path (required)
+--                      - files: the source files to track
+--                      - values: the values to track (e.g. flags, program)
 --
+-- @code
 -- depend.on_changed(function ()
---     -- do some thing
---     -- ..
---
---     -- maybe need update dependent files
---     dependinfo.files = {""}
---
---     -- return new dependinfo (optional)
---     return {files = {}, ..}
---
--- end, {dependfile = "/xx/xx",
---       values = {compinst:program(), compflags},
---       files = {sourcefile, ...}})
+--     -- do build work here
+-- end, {dependfile = target:dependfile(objectfile),
+--       files = {sourcefile},
+--       values = {compinst:program(), compflags}})
+-- @endcode
 --
 function on_changed(callback, opt)
     opt = opt or {}
diff --git a/xmake/modules/private/utils/batchcmds.lua b/xmake/modules/private/utils/batchcmds.lua
index 378f4f0f5..3f584b286 100644
--- a/xmake/modules/private/utils/batchcmds.lua
+++ b/xmake/modules/private/utils/batchcmds.lua
@@ -249,22 +249,38 @@ function _runcmds(cmds, opt)
     end
 end
 
--- is empty? no commands
+-- is empty? (no pending commands)
+--
+-- @return      true if no commands
+--
 function batchcmds:empty()
     return #self:cmds() == 0
 end
 
--- get commands
+-- get all pending commands
+--
+-- @return      the commands array
+--
 function batchcmds:cmds()
     return self._CMDS
 end
 
--- add command: os.runv
+-- add command: run program silently
+--
+-- @param program   the program path
+-- @param argv      the arguments (optional)
+-- @param opt       the options, e.g. {envs = {}}
+--
 function batchcmds:runv(program, argv, opt)
     table.insert(self:cmds(), {kind = "runv", program = program, argv = argv, opt = opt})
 end
 
--- add command: os.vrunv
+-- add command: run program with verbose output
+--
+-- @param program   the program path
+-- @param argv      the arguments (optional)
+-- @param opt       the options, e.g. {envs = {}}
+--
 function batchcmds:vrunv(program, argv, opt)
     table.insert(self:cmds(), {kind = "vrunv", program = program, argv = argv, opt = opt})
 end
@@ -279,7 +295,12 @@ function batchcmds:vexecv(program, argv, opt)
     table.insert(self:cmds(), {kind = "vexecv", program = program, argv = argv, opt = opt})
 end
 
--- add command: run lua script file, command or module
+-- add command: run lua script
+--
+-- @param script the lua script path or module name
+-- @param argv   the arguments (optional)
+-- @param opt    the options (optional)
+--
 function batchcmds:lua(script, argv, opt)
     table.insert(self:cmds(), {kind = "lua", script = script, argv = argv, opt = opt})
 end
@@ -289,7 +310,12 @@ function batchcmds:vlua(script, argv, opt)
     table.insert(self:cmds(), {kind = "vlua", script = script, argv = argv, opt = opt})
 end
 
--- add command: compiler.compile
+-- add command: compile source files
+--
+-- @param sourcefiles the source file paths
+-- @param objectfile  the output object file path
+-- @param opt         the options, e.g. {sourcekind = "cxx", configs = {}}
+--
 function batchcmds:compile(sourcefiles, objectfile, opt)
 
     -- bind target if exists
@@ -365,7 +391,12 @@ function batchcmds:compilev(argv, opt)
     end
 end
 
--- add command: linker.link
+-- add command: link object files
+--
+-- @param objectfiles the object file paths
+-- @param targetfile  the output target file path
+-- @param opt         the options (optional)
+--
 function batchcmds:link(objectfiles, targetfile, opt)
 
     -- bind target if exists
@@ -406,27 +437,48 @@ function batchcmds:link(objectfiles, targetfile, opt)
     self:vrunv(program, argv, {envs = table.join(linker_inst:runenvs(), opt.envs)})
 end
 
--- add command: os.mkdir
+-- add command: create directory
+--
+-- @param dir   the directory path
+--
 function batchcmds:mkdir(dir)
     table.insert(self:cmds(), {kind = "mkdir", dir = dir})
 end
 
--- add command: os.rmdir
+-- add command: remove directory
+--
+-- @param dir   the directory path
+-- @param opt   the options, e.g. {emptydirs = true}
+--
 function batchcmds:rmdir(dir, opt)
     table.insert(self:cmds(), {kind = "rmdir", dir = dir, opt = opt})
 end
 
--- add command: os.rm
+-- add command: remove file
+--
+-- @param filepath the file path
+-- @param opt      the options (optional)
+--
 function batchcmds:rm(filepath, opt)
     table.insert(self:cmds(), {kind = "rm", filepath = filepath, opt = opt})
 end
 
--- add command: os.cp
+-- add command: copy files or directories
+--
+-- @param srcpath   the source path (supports patterns)
+-- @param dstpath   the destination path
+-- @param opt       the options, e.g. {rootdir = "", symlink = true}
+--
 function batchcmds:cp(srcpath, dstpath, opt)
     table.insert(self:cmds(), {kind = "cp", srcpath = srcpath, dstpath = dstpath, opt = opt})
 end
 
--- add command: os.mv
+-- add command: move files or directories
+--
+-- @param srcpath   the source path
+-- @param dstpath   the destination path
+-- @param opt       the options (optional)
+--
 function batchcmds:mv(srcpath, dstpath, opt)
     table.insert(self:cmds(), {kind = "mv", srcpath = srcpath, dstpath = dstpath, opt = opt})
 end
@@ -436,17 +488,30 @@ function batchcmds:ln(srcpath, dstpath, opt)
     table.insert(self:cmds(), {kind = "ln", srcpath = srcpath, dstpath = dstpath, opt = opt})
 end
 
--- add command: os.cd
+-- add command: change directory
+--
+-- @param dir   the directory path
+-- @param opt   the options (optional)
+--
 function batchcmds:cd(dir, opt)
     table.insert(self:cmds(), {kind = "cd", dir = dir, opt = opt})
 end
 
--- add command: show
+-- add command: show message
+--
+-- @param format the format string
+-- @param ...    the format arguments
+--
 function batchcmds:show(format, ...)
     table.insert(self:cmds(), {kind = "show", format = format, argv = table.pack(...)})
 end
 
--- add command: show progress
+-- add command: show message with progress
+--
+-- @param progress  the progress value (0 ~ 100)
+-- @param format    the format string with color markup
+-- @param ...       the format arguments
+--
 function batchcmds:show_progress(progress, format, ...)
     table.insert(self:cmds(), {kind = "show_progress", progress = progress, format = format, argv = table.pack(...)})
 end
@@ -472,6 +537,10 @@ function batchcmds:change_rpath(filepath, rpath_old, rpath_new, opt)
 end
 
 -- add raw command for the specific generator or xpack format
+--
+-- @param kind   the command kind
+-- @param rawstr the raw command string
+--
 function batchcmds:rawcmd(kind, rawstr)
     table.insert(self:cmds(), {kind = kind, rawstr = rawstr})
 end
@@ -481,7 +550,10 @@ function batchcmds:depinfo()
     return self._DEPINFO
 end
 
--- add dependent files
+-- add dependent files for incremental build
+--
+-- @param ...   the dependent file paths
+--
 function batchcmds:add_depfiles(...)
     local depinfo = self._DEPINFO or {}
     depinfo.files = depinfo.files or {}
@@ -497,14 +569,20 @@ function batchcmds:add_depvalues(...)
     self._DEPINFO = depinfo
 end
 
--- set the last mtime of dependent files and values
+-- set the last modification time for dependency checking
+--
+-- @param lastmtime  the last modification time
+--
 function batchcmds:set_depmtime(lastmtime)
     local depinfo = self._DEPINFO or {}
     depinfo.lastmtime = lastmtime
     self._DEPINFO = depinfo
 end
 
--- set cache file of depend info
+-- set the cache file path for dependency info
+--
+-- @param cachefile  the dependency cache file path
+--
 function batchcmds:set_depcache(cachefile)
     local depinfo = self._DEPINFO or {}
     depinfo.dependfile = cachefile
diff --git a/xmake/modules/utils/progress.lua b/xmake/modules/utils/progress.lua
index 3e7598ac2..8d7ab53f3 100644
--- a/xmake/modules/utils/progress.lua
+++ b/xmake/modules/utils/progress.lua
@@ -383,7 +383,12 @@ function set_target(progress, target)
     end
 end
 
--- show the message with progress
+-- show the message with progress indicator
+--
+-- @param progress  the progress value (0 ~ 100)
+-- @param format    the format string with color markup
+-- @param ...       the format arguments
+--
 function show(progress, format, ...)
     local target_prefix = _get_target_name_prefix(progress)
     if target_prefix then
@@ -403,8 +408,11 @@ function show(progress, format, ...)
     end
 end
 
--- print additional output logs with colors outside the progress log area, such as warning logs.
--- it's used when the progress style is multirow/singlerow refresh.
+-- print additional output logs outside the progress area (for warnings, etc.)
+--
+-- @param format    the format string with color markup
+-- @param ...       the format arguments
+--
 function show_output(format, ...)
     local refresh_mode = _g.refresh_mode
     if refresh_mode == "singlerow" then