update more comments

18 files changed, 590 insertions, 116 deletions

diff --git a/xmake/core/base/bloom_filter.lua b/xmake/core/base/bloom_filter.lua
index d82618be9..31f61bdf9 100644
--- a/xmake/core/base/bloom_filter.lua
+++ b/xmake/core/base/bloom_filter.lua
@@ -54,12 +54,18 @@ function _instance.new(handle)
     return instance
 end
 
--- get cdata of the bloom filter
+-- get the internal cdata handle
+--
+-- @return      the cdata
+--
 function _instance:cdata()
     return self._HANDLE
 end
 
--- get the bloom filter data
+-- get serialized bloom filter data
+--
+-- @return      the data bytes, or nil and error info
+--
 function _instance:data()
     -- ensure opened
     local ok, errors = self:_ensure_opened()
@@ -78,7 +84,11 @@ function _instance:data()
     return bytes(size, data)
 end
 
--- set the bloom filter data
+-- load bloom filter from serialized data
+--
+-- @param data  the data bytes
+-- @return      true on success, or false and error info
+--
 function _instance:data_set(data)
     -- ensure opened
     local ok, errors = self:_ensure_opened()
@@ -95,7 +105,10 @@ function _instance:data_set(data)
     return bloom_filter._data_set(self:cdata(), dataaddr, datasize)
 end
 
--- clear the bloom filter data
+-- clear all data in the bloom filter
+--
+-- @return      true on success, or false and error info
+--
 function _instance:clear()
     -- ensure opened
     local ok, errors = self:_ensure_opened()
diff --git a/xmake/core/base/coroutine.lua b/xmake/core/base/coroutine.lua
index 2ed91c354..2335f29d8 100644
--- a/xmake/core/base/coroutine.lua
+++ b/xmake/core/base/coroutine.lua
@@ -29,7 +29,12 @@ local string    = require("base/string")
 -- save original interfaces
 coroutine._resume  = coroutine._resume or coroutine.resume
 
--- resume coroutine
+-- resume coroutine with enhanced error reporting
+--
+-- @param co    the coroutine to resume
+-- @param ...   the resume arguments
+-- @return      true and results on success, or false and error info
+--
 function coroutine.resume(co, ...)
     local ok, results = coroutine._resume(co, ...)
     if not ok then
diff --git a/xmake/core/base/debugger.lua b/xmake/core/base/debugger.lua
index f62871482..f9a5e451e 100644
--- a/xmake/core/base/debugger.lua
+++ b/xmake/core/base/debugger.lua
@@ -47,14 +47,17 @@ function debugger:_start_emmylua_debugger()
     return true
 end
 
--- start debugging
+-- start the debugger (attach to IDE)
 function debugger:start()
     if self:has_emmylua() then
         return self:_start_emmylua_debugger()
     end
 end
 
--- has emmylua debugger?
+-- has EmmyLua debugger available?
+--
+-- @return      true if available
+--
 function debugger:has_emmylua()
     local debugger_libfile = os.getenv("EMMYLUA_DEBUGGER")
     if debugger_libfile and os.isfile(debugger_libfile) then
@@ -62,7 +65,10 @@ function debugger:has_emmylua()
     end
 end
 
--- debugger is enabled?
+-- is the debugger enabled?
+--
+-- @return      true if enabled via --debugger option
+--
 function debugger:enabled()
     return self:has_emmylua()
 end
diff --git a/xmake/core/base/libc.lua b/xmake/core/base/libc.lua
index f9a12931e..b72c77ce4 100644
--- a/xmake/core/base/libc.lua
+++ b/xmake/core/base/libc.lua
@@ -44,6 +44,12 @@ if ffi then
     ]]
 end
 
+-- allocate memory
+--
+-- @param size  the memory size in bytes
+-- @param opt   the options, e.g. {zeroed = true}
+-- @return      the cdata pointer
+--
 function libc.malloc(size, opt)
     if ffi then
         if opt and opt.gc then
@@ -60,6 +66,10 @@ function libc.malloc(size, opt)
     end
 end
 
+-- free memory
+--
+-- @param data  the cdata pointer to free
+--
 function libc.free(data)
     if ffi then
         return ffi.C.free(data)
@@ -68,6 +78,12 @@ function libc.free(data)
     end
 end
 
+-- copy memory
+--
+-- @param dst   the destination pointer
+-- @param src   the source pointer
+-- @param size  the copy size in bytes
+--
 function libc.memcpy(dst, src, size)
     if ffi then
         return ffi.copy(dst, src, size)
@@ -76,6 +92,12 @@ function libc.memcpy(dst, src, size)
     end
 end
 
+-- move memory (handles overlapping regions)
+--
+-- @param dst   the destination pointer
+-- @param src   the source pointer
+-- @param size  the move size in bytes
+--
 function libc.memmov(dst, src, size)
     if ffi then
         return ffi.C.memmove(dst, src, size)
@@ -84,6 +106,12 @@ function libc.memmov(dst, src, size)
     end
 end
 
+-- fill memory with a byte value
+--
+-- @param data  the memory pointer
+-- @param ch    the byte value
+-- @param size  the fill size in bytes
+--
 function libc.memset(data, ch, size)
     if ffi then
         return ffi.fill(data, size, ch)
@@ -92,6 +120,12 @@ function libc.memset(data, ch, size)
     end
 end
 
+-- duplicate a string with length limit
+--
+-- @param s     the source string
+-- @param n     the maximum length
+-- @return      the new cdata string pointer
+--
 function libc.strndup(s, n)
     if ffi then
         return ffi.string(s, n)
@@ -104,6 +138,12 @@ function libc.strndup(s, n)
     end
 end
 
+-- get byte value at the given offset
+--
+-- @param data    the memory pointer
+-- @param offset  the byte offset
+-- @return        the byte value
+--
 function libc.byteof(data, offset)
     if ffi then
         return data[offset]
@@ -112,6 +152,12 @@ function libc.byteof(data, offset)
     end
 end
 
+-- set byte value at the given offset
+--
+-- @param data    the memory pointer
+-- @param offset  the byte offset
+-- @param value   the byte value
+--
 function libc.setbyte(data, offset, value)
     if ffi then
         data[offset] = value
@@ -120,6 +166,12 @@ function libc.setbyte(data, offset, value)
     end
 end
 
+-- get cdata pointer from string or bytes
+--
+-- @param data  the string or bytes data
+-- @param opt   the options (optional)
+-- @return      the cdata pointer
+--
 function libc.dataptr(data, opt)
     opt = opt or {}
     if ffi and opt.ffi ~= false then
@@ -133,6 +185,12 @@ function libc.dataptr(data, opt)
     end
 end
 
+-- get the numeric address of a cdata pointer
+--
+-- @param data  the cdata pointer
+-- @param opt   the options (optional)
+-- @return      the address as number
+--
 function libc.ptraddr(data, opt)
     opt = opt or {}
     if ffi and opt.ffi ~= false then
diff --git a/xmake/core/base/list.lua b/xmake/core/base/list.lua
index 671d17be8..4caed81bc 100644
--- a/xmake/core/base/list.lua
+++ b/xmake/core/base/list.lua
@@ -24,7 +24,7 @@ local object = require("base/object")
 -- define module
 local list = list or object { _init = {"_length"} } {0}
 
--- clear list
+-- clear all elements
 function list:clear()
     self._length = 0
     self._first  = nil
@@ -136,37 +136,59 @@ function list:remove_last()
     return t
 end
 
--- push item to tail
+-- push element to the back
+--
+-- @param t     the element
+--
 function list:push(t)
     self:insert_last(t)
 end
 
--- pop item from tail
+-- pop element from the back
+--
+-- @return      the removed element
+--
 function list:pop()
     self:remove_last()
 end
 
--- shift item: 1 2 3 <- 2 3
+-- shift element from the front
+--
+-- @return      the removed element
+--
 function list:shift()
     self:remove_first()
 end
 
--- unshift item: 1 2 -> t 1 2
+-- unshift element to the front
+--
+-- @param t     the element
+--
 function list:unshift(t)
     self:insert_first(t)
 end
 
--- get first item
+-- get the first element
+--
+-- @return      the first element, or nil if empty
+--
 function list:first()
     return self._first
 end
 
--- get last item
+-- get the last element
+--
+-- @return      the last element, or nil if empty
+--
 function list:last()
     return self._last
 end
 
--- get next item
+-- get the next element after the given one
+--
+-- @param last  the current element
+-- @return      the next element, or nil
+--
 function list:next(last)
     if last then
         return last._next
@@ -175,7 +197,11 @@ function list:next(last)
     end
 end
 
--- get the previous item
+-- get the previous element before the given one
+--
+-- @param last  the current element
+-- @return      the previous element, or nil
+--
 function list:prev(last)
     if last then
         return last._prev
@@ -184,12 +210,18 @@ function list:prev(last)
     end
 end
 
--- get list size
+-- get the list size
+--
+-- @return      the number of elements
+--
 function list:size()
     return self._length
 end
 
--- is empty?
+-- is the list empty?
+--
+-- @return      true if empty
+--
 function list:empty()
     return self:size() == 0
 end
@@ -202,6 +234,10 @@ end
 --     print(item)
 -- end
 --
+-- iterate elements from front to back
+--
+-- @return      the iterator function
+--
 function list:items()
     local iter = function (list, item)
         return list:next(item)
@@ -209,7 +245,10 @@ function list:items()
     return iter, self, nil
 end
 
--- get reverse items
+-- iterate elements from back to front
+--
+-- @return      the reverse iterator function
+--
 function list:ritems()
     local iter = function (list, item)
         return list:prev(item)
diff --git a/xmake/core/base/profiler.lua b/xmake/core/base/profiler.lua
index c00d80964..c26c96645 100644
--- a/xmake/core/base/profiler.lua
+++ b/xmake/core/base/profiler.lua
@@ -165,7 +165,7 @@ function profiler:start()
     end
 end
 
--- stop profiling
+-- stop profiling and print results
 function profiler:stop()
     if self:is_trace() then
         debug.sethook()
@@ -231,7 +231,11 @@ function profiler:stop()
    end
 end
 
--- enter the given tag for perf:tag
+-- enter the given performance tag
+--
+-- @param name  the tag name
+-- @param ...   the format arguments for tag name
+--
 function profiler:enter(name, ...)
     local is_perf_tag = self._IS_PERF_TAG
     if is_perf_tag == nil then
@@ -246,7 +250,11 @@ function profiler:enter(name, ...)
     end
 end
 
--- leave the given tag for perf:tag
+-- leave the given performance tag
+--
+-- @param name  the tag name
+-- @param ...   the format arguments for tag name
+--
 function profiler:leave(name, ...)
     local is_perf_tag = self._IS_PERF_TAG
     if is_perf_tag == nil then
@@ -264,7 +272,10 @@ function profiler:leave(name, ...)
     end
 end
 
--- get profiler mode, e.g. perf:call, perf:tag, perf:process, trace
+-- get profiler mode
+--
+-- @return      the mode string, e.g. "perf:call", "perf:tag", "perf:process", "trace"
+--
 function profiler:mode()
     local mode = self._MODE
     if mode == nil then
@@ -274,13 +285,20 @@ function profiler:mode()
     return mode or nil
 end
 
--- is trace?
+-- is trace mode?
+--
+-- @return      true if trace mode
+--
 function profiler:is_trace()
     local mode = self:mode()
     return mode and mode == "trace"
 end
 
--- is perf?
+-- is perf mode?
+--
+-- @param name  the specific perf type (optional), e.g. "call", "tag", "process"
+-- @return      true if perf mode
+--
 function profiler:is_perf(name)
     local mode = self:mode()
     if mode and name then
@@ -288,7 +306,10 @@ function profiler:is_perf(name)
     end
 end
 
--- profiler is enabled?
+-- is the profiler enabled?
+--
+-- @return      true if enabled via --profile option
+--
 function profiler:enabled()
     return self:is_perf("call") or self:is_perf("tag") or self:is_trace()
 end
diff --git a/xmake/core/base/queue.lua b/xmake/core/base/queue.lua
index e7f306c11..543518356 100644
--- a/xmake/core/base/queue.lua
+++ b/xmake/core/base/queue.lua
@@ -24,20 +24,26 @@ local object = require("base/object")
 -- define module
 local queue = queue or object {_init = {"_first", "_last"}} {1, 0}
 
--- clear queue
+-- clear all elements
 function queue:clear()
     self._first = 1
     self._last = 0
 end
 
--- push item to queue
+-- push an item to the back of the queue
+--
+-- @param item  the item to push
+--
 function queue:push(item)
     local last = self._last + 1
     self._last = last
     self[last] = item
 end
 
--- pop item from queue
+-- pop an item from the front of the queue
+--
+-- @return      the popped item, or nil if empty
+--
 function queue:pop()
     local first = self._first
     if first > self._last then
@@ -50,17 +56,26 @@ function queue:pop()
     return value
 end
 
--- get queue size
+-- get the queue size
+--
+-- @return      the number of elements
+--
 function queue:size()
     return self._last - self._first + 1
 end
 
--- is queue empty?
+-- is the queue empty?
+--
+-- @return      true if empty
+--
 function queue:empty()
     return self._first > self._last
 end
 
--- peek the first item of queue
+-- peek the first item without removing
+--
+-- @return      the first element, or nil if empty
+--
 function queue:first()
     if self._first > self._last then
         return nil
@@ -68,7 +83,10 @@ function queue:first()
     return self[self._first]
 end
 
--- peek the last item of queue
+-- peek the last item without removing
+--
+-- @return      the last element, or nil if empty
+--
 function queue:last()
     if self._first > self._last then
         return nil
@@ -107,7 +125,10 @@ function queue:ritems()
     end
 end
 
--- clone queue
+-- clone the queue
+--
+-- @return      the cloned queue
+--
 function queue:clone()
     local q = queue.new()
     for i = self._first, self._last do
diff --git a/xmake/core/base/socket.lua b/xmake/core/base/socket.lua
index fb4536e24..393edd199 100644
--- a/xmake/core/base/socket.lua
+++ b/xmake/core/base/socket.lua
@@ -131,7 +131,12 @@ function _instance:ctrl(code, value)
     return ok, errors
 end
 
--- bind socket
+-- bind socket to address and port
+--
+-- @param addr  the bind address
+-- @param port  the bind port
+-- @return      true on success, or false and error info
+--
 function _instance:bind(addr, port)
 
     -- ensure opened
@@ -171,7 +176,11 @@ function _instance:bind_unix(addr, opt)
     return ok, errors
 end
 
--- listen socket
+-- listen for incoming connections
+--
+-- @param backlog the maximum pending connections
+-- @return      true on success, or false and error info
+--
 function _instance:listen(backlog)
 
     -- ensure opened
@@ -188,7 +197,11 @@ function _instance:listen(backlog)
     return ok, errors
 end
 
--- accept socket
+-- accept an incoming connection
+--
+-- @param opt   the options (optional)
+-- @return      the client socket, or nil on timeout
+--
 function _instance:accept(opt)
 
     -- ensure opened
@@ -217,7 +230,13 @@ function _instance:accept(opt)
     return sock, errors
 end
 
--- connect socket
+-- connect to remote address and port
+--
+-- @param addr  the remote address
+-- @param port  the remote port
+-- @param opt   the options (optional)
+-- @return      1 on success, 0 on timeout, -1 on error
+--
 function _instance:connect(addr, port, opt)
 
     -- ensure opened
@@ -281,6 +300,11 @@ function _instance:connect_unix(addr, opt)
 end
 
 -- send data to socket
+--
+-- @param data  the data to send (string or bytes)
+-- @param opt   the options, e.g. {block = true}
+-- @return      the real sent size, or -1 on error
+--
 function _instance:send(data, opt)
 
     -- ensure opened
@@ -346,7 +370,12 @@ function _instance:send(data, opt)
     return send, errors
 end
 
--- send file to socket
+-- send file data to socket (zero-copy)
+--
+-- @param file  the file object
+-- @param opt   the options (optional)
+-- @return      the real sent size, or -1 on error
+--
 function _instance:sendfile(file, opt)
 
     -- ensure the socket opened
@@ -415,7 +444,13 @@ function _instance:sendfile(file, opt)
     return send, errors
 end
 
--- recv data from socket
+-- receive data from socket
+--
+-- @param buff  the buffer to receive data
+-- @param size  the max receive size
+-- @param opt   the options, e.g. {block = true}
+-- @return      the real received size, or -1 on error
+--
 function _instance:recv(buff, size, opt)
     assert(buff)
 
@@ -488,7 +523,14 @@ function _instance:recv(buff, size, opt)
     return recv, data_or_errors
 end
 
--- send udp data to peer
+-- send UDP data to peer
+--
+-- @param data  the data to send
+-- @param addr  the peer address
+-- @param port  the peer port
+-- @param opt   the options (optional)
+-- @return      the real sent size, or -1 on error
+--
 function _instance:sendto(data, addr, port, opt)
 
     -- ensure opened
@@ -553,7 +595,13 @@ function _instance:sendto(data, addr, port, opt)
     return send, errors
 end
 
--- recv udp data from peer
+-- receive UDP data from peer
+--
+-- @param buff  the buffer to receive data
+-- @param size  the max receive size
+-- @param opt   the options (optional)
+-- @return      the real received size, the peer address, the peer port
+--
 function _instance:recvfrom(buff, size, opt)
     assert(buff)
 
@@ -624,7 +672,12 @@ function _instance:recvfrom(buff, size, opt)
     return recv, data_or_errors, addr, port
 end
 
--- wait socket events
+-- wait for socket events
+--
+-- @param events    the events to wait, e.g. socket.EV_RECV, socket.EV_SEND
+-- @param timeout   the timeout in milliseconds, -1 for infinite
+-- @return          the received events, or 0 on timeout
+--
 function _instance:wait(events, timeout)
 
     -- ensure opened
@@ -661,7 +714,10 @@ function _instance:kill()
     return true
 end
 
--- close socket
+-- close the socket
+--
+-- @return      true on success
+--
 function _instance:close()
 
     -- ensure opened
diff --git a/xmake/core/base/tty.lua b/xmake/core/base/tty.lua
index bd7b60277..2b9aa91bc 100644
--- a/xmake/core/base/tty.lua
+++ b/xmake/core/base/tty.lua
@@ -496,7 +496,10 @@ function tty.has_emoji()
     return has_emoji
 end
 
--- has vtansi?
+-- does the terminal support VT/ANSI escape codes?
+--
+-- @return      true if supported
+--
 function tty.has_vtansi()
     return tty.has_color8()
 end
@@ -658,7 +661,10 @@ function tty.term_mode(stdtype, newmode)
     return oldmode
 end
 
--- get session id
+-- get the terminal session id
+--
+-- @return      the session id string
+--
 function tty.session_id()
     local session_id = tty._SESSION_ID
     if session_id == nil then
diff --git a/xmake/core/base/xmake.lua b/xmake/core/base/xmake.lua
index d25e60147..53971de8c 100644
--- a/xmake/core/base/xmake.lua
+++ b/xmake/core/base/xmake.lua
@@ -24,12 +24,18 @@ local xmake = xmake or {}
 -- load modules
 local semver = require("base/semver")
 
--- get name
+-- get xmake program name
+--
+-- @return      the name string, e.g. "xmake"
+--
 function xmake.name()
     return xmake._NAME or "xmake"
 end
 
--- get xmake version, e.g. v2.5.8+dev.d4cff6e11
+-- get xmake version
+--
+-- @return      the semver version object, e.g. xmake.version():ge("3.0.0")
+--
 function xmake.version()
     if xmake._VERSION_CACHE == nil then
         xmake._VERSION_CACHE = semver.new(xmake._VERSION) or false
@@ -38,41 +44,65 @@ function xmake.version()
 end
 
 -- get the xmake binary architecture
+--
+-- @return      the architecture string, e.g. "x86_64", "arm64"
+--
 function xmake.arch()
     return xmake._XMAKE_ARCH
 end
 
--- get the git branch of xmake version, e.g. build: {"dev", "d4cff6e11"}
+-- get the git branch and commit of xmake version
+--
+-- @return      the branch string and commit hash
+--
 function xmake.branch()
     return xmake.version():build()[1]
 end
 
--- get the program directory
+-- get the xmake program scripts directory
+--
+-- @return      the program directory path
+--
 function xmake.programdir()
     return xmake._PROGRAM_DIR
 end
 
--- get the program file
+-- get the xmake program binary file path
+--
+-- @return      the program file path
+--
 function xmake.programfile()
     return xmake._PROGRAM_FILE
 end
 
--- use luajit?
+-- is using LuaJIT runtime?
+--
+-- @return      true if LuaJIT
+--
 function xmake.luajit()
     return xmake._LUAJIT
 end
 
--- is embed?
+-- is embedded via libxmake (xmake.cli)?
+--
+-- @return      true if embedded
+--
 function xmake.is_embed()
     return xmake._EMBED or false
 end
 
--- in main thread?
+-- is running in the main thread?
+--
+-- @return      true if in main thread
+--
 function xmake.in_main_thread()
     return xmake._THREAD_CALLBACK == nil
 end
 
--- get command arguments
+-- get the command line arguments
+--
+-- @return      the arguments array
+--
 function xmake.argv()
     return xmake._ARGV
 end
diff --git a/xmake/core/package/component.lua b/xmake/core/package/component.lua
index d93a4f7fb..c55dc4a73 100644
--- a/xmake/core/package/component.lua
+++ b/xmake/core/package/component.lua
@@ -46,36 +46,63 @@ function _instance.new(name, opt)
 end
 
 -- get the component name
+--
+-- @return      the component name string
+--
 function _instance:name()
     return self._NAME
 end
 
--- get the type: component
+-- get the instance type
+--
+-- @return      "component"
+--
 function _instance:type()
     return "component"
 end
 
--- get the it's package
+-- get the parent package
+--
+-- @return      the package instance
+--
 function _instance:package()
     return self._PACKAGE
 end
 
--- get the component configuration
+-- get the component configuration value
+--
+-- @param name  the config name
+-- @return      the config value
+--
 function _instance:get(name)
     return self._INFO:get(name)
 end
 
 -- set the value to the component info
+--
+-- @param name  the info name
+-- @param ...   the values
+--
 function _instance:set(name, ...)
     self._INFO:apival_set(name, ...)
 end
 
 -- add the value to the component info
+--
+-- @param name  the info name
+-- @param ...   the values to add
+--
 function _instance:add(name, ...)
     self._INFO:apival_add(name, ...)
 end
 
 -- get the extra configuration
+--
+-- @param name  the config name
+-- @param item  the config item
+-- @param key   the config key (optional)
+-- @return      the extra config value
+--
 function _instance:extraconf(name, item, key)
     local conf = self._INFO:extraconf(name, item, key)
     if conf == nil then
diff --git a/xmake/core/package/repository.lua b/xmake/core/package/repository.lua
index 7f140c098..8141d53d2 100644
--- a/xmake/core/package/repository.lua
+++ b/xmake/core/package/repository.lua
@@ -48,21 +48,33 @@ end
 
 
 -- get the repository name
+--
+-- @return      the name string
+--
 function _instance:name()
     return self._NAME
 end
 
 -- get the repository url
+--
+-- @return      the url string
+--
 function _instance:url()
     return self._URL
 end
 
 -- get the repository branch
+--
+-- @return      the branch string
+--
 function _instance:branch()
     return self._BRANCH
 end
 
--- get the current commit
+-- get the current commit hash
+--
+-- @return      the commit string
+--
 function _instance:commit()
     return self._COMMIT
 end
@@ -73,11 +85,17 @@ function _instance:commit_set(commit)
 end
 
 -- is global repository?
+--
+-- @return      true if global
+--
 function _instance:is_global()
     return self._IS_GLOBAL
 end
 
--- get the repository directory
+-- get the repository directory on disk
+--
+-- @return      the directory path
+--
 function _instance:directory()
     return self._DIRECTORY
 end
@@ -125,7 +143,11 @@ function repository.apis()
     }
 end
 
--- get the local or global repository directory
+-- get the repositories root directory
+--
+-- @param is_global  get global directory if true
+-- @return          the directory path
+--
 function repository.directory(is_global)
 
     -- get directory
@@ -136,7 +158,14 @@ function repository.directory(is_global)
     end
 end
 
--- load the repository
+-- load a repository
+--
+-- @param name       the repository name
+-- @param url        the repository url
+-- @param branch     the repository branch
+-- @param is_global  is global repository?
+-- @return           the repository instance
+--
 function repository.load(name, url, branch, is_global)
 
     -- check url
@@ -165,6 +194,11 @@ function repository.load(name, url, branch, is_global)
 end
 
 -- get repository url from the given name
+--
+-- @param name       the repository name
+-- @param is_global  search global repositories?
+-- @return           the repository url
+--
 function repository.get(name, is_global)
 
     -- get it
@@ -179,7 +213,13 @@ function repository.get(name, is_global)
     end
 end
 
--- add repository url to the given name
+-- add a repository
+--
+-- @param name       the repository name
+-- @param url        the repository url
+-- @param branch     the repository branch
+-- @param is_global  add as global repository?
+--
 function repository.add(name, url, branch, is_global)
 
     -- no name?
@@ -199,7 +239,11 @@ function repository.add(name, url, branch, is_global)
     return true
 end
 
--- remove repository from gobal or local directory
+-- remove a repository
+--
+-- @param name       the repository name
+-- @param is_global  remove from global?
+--
 function repository.remove(name, is_global)
 
     -- get repositories
@@ -225,7 +269,11 @@ function repository.clear(is_global)
 end
 
 
--- get all repositories from global or local directory
+-- get all repositories
+--
+-- @param is_global  get global repositories?
+-- @return           the repositories table {name = repo, ...}
+--
 function repository.repositories(is_global)
     return repository._cache(is_global):get("repositories")
 end
diff --git a/xmake/core/package/scheme.lua b/xmake/core/package/scheme.lua
index d03cce0a9..a1baa7301 100644
--- a/xmake/core/package/scheme.lua
+++ b/xmake/core/package/scheme.lua
@@ -51,31 +51,50 @@ function _instance.new(name, opt)
 end
 
 -- get the scheme name
+--
+-- @return      the scheme name string
+--
 function _instance:name()
     return self._NAME
 end
 
--- get the type: scheme
+-- get the instance type
+--
+-- @return      "scheme"
+--
 function _instance:type()
     return "scheme"
 end
 
--- is default scheme?
+-- is the default scheme?
+--
+-- @return      true if default
+--
 function _instance:is_default()
     return self:name() == "__default__"
 end
 
--- is precompiled scheme?
+-- is precompiled binary scheme?
+--
+-- @return      true if precompiled
+--
 function _instance:is_precompiled()
     return self:name() == "__precompiled__"
 end
 
--- get the it's package
+-- get the associated package
+--
+-- @return      the package instance
+--
 function _instance:package()
     return self._PACKAGE
 end
 
--- get the scheme configuration
+-- get the scheme configuration value
+--
+-- @param name  the config name
+-- @return      the config value
+--
 function _instance:get(name)
     local value = self._INFO:get(name)
     if value == nil and self:is_default() and self:package() then
@@ -85,6 +104,10 @@ function _instance:get(name)
 end
 
 -- set the value to scheme info
+--
+-- @param name  the info name
+-- @param ...   the values
+--
 function _instance:set(name, ...)
     self._INFO:apival_set(name, ...)
 end
@@ -108,7 +131,10 @@ function _instance:extraconf_set(name, item, key, value)
     return self._INFO:extraconf_set(name, item, key, value)
 end
 
--- get urls
+-- get the source urls
+--
+-- @return      the urls array
+--
 function _instance:urls()
     local urls = self._URLS
     if urls == nil then
diff --git a/xmake/core/project/cache.lua b/xmake/core/project/cache.lua
index 280df52e8..669ec1a03 100644
--- a/xmake/core/project/cache.lua
+++ b/xmake/core/project/cache.lua
@@ -86,22 +86,30 @@ function cache._instance(scopename)
     return instance
 end
 
--- get the value
+-- get the cached value
+--
+-- @param name  the cache key
+-- @return      the cached value
+--
 function cache:get(name)
     return self._CACHEDATA[name]
 end
 
--- set the value
+-- set the cached value
+--
+-- @param name  the cache key
+-- @param value the value to cache
+--
 function cache:set(name, value)
     self._CACHEDATA[name] = value
 end
 
--- clear all
+-- clear all cached values
 function cache:clear()
     self._CACHEDATA = {__version = xmake._VERSION_SHORT}
 end
 
--- flush to cache file
+-- flush cached values to file
 function cache:flush()
 
     -- flush the version
diff --git a/xmake/core/project/option.lua b/xmake/core/project/option.lua
index f754b4efc..62687a106 100644
--- a/xmake/core/project/option.lua
+++ b/xmake/core/project/option.lua
@@ -388,11 +388,17 @@ function _instance:check()
 end
 
 -- get the option value
+--
+-- @return      the option value
+--
 function _instance:value()
     return config.get(self:fullname())
 end
 
 -- set the option value
+--
+-- @param value the value to set
+--
 function _instance:set_value(value)
     config.set(self:fullname(), value)
     self:_save()
@@ -404,7 +410,10 @@ function _instance:clear()
     self:_clear()
 end
 
--- this option is enabled?
+-- is this option enabled?
+--
+-- @return      true if enabled
+--
 function _instance:enabled()
     return config.get(self:fullname())
 end
@@ -437,12 +446,19 @@ function _instance:info()
     return self._INFO:info()
 end
 
--- get the type: option
+-- get the instance type
+--
+-- @return      "option"
+--
 function _instance:type()
     return "option"
 end
 
--- get the option info
+-- get the option info value
+--
+-- @param name  the info name
+-- @return      the info value
+--
 function _instance:get(name)
     return self._INFO:get(name)
 end
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