update more comments

10 files changed, 311 insertions, 56 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