update more comments

6 files changed, 136 insertions, 16 deletions

diff --git a/xmake/core/base/fwatcher.lua b/xmake/core/base/fwatcher.lua
index 3844f5877..9fc04722e 100644
--- a/xmake/core/base/fwatcher.lua
+++ b/xmake/core/base/fwatcher.lua
@@ -153,17 +153,30 @@ function _instance:_ensure_opened()
     return true
 end
 
--- add watchdir
+-- add a directory to watch
+--
+-- @param watchdir  the directory path to watch
+-- @param opt       the options, e.g. {recursion = true}
+-- @return          true on success, or false and error info
+--
 function fwatcher.add(watchdir, opt)
     return _instance:add(watchdir, opt)
 end
 
--- remove watchdir
+-- remove a directory from watch
+--
+-- @param watchdir  the directory path to remove
+-- @return          true on success, or false and error info
+--
 function fwatcher.remove(watchdir)
     return _instance:remove(watchdir)
 end
 
--- wait event
+-- wait for file system event
+--
+-- @param timeout   the timeout in milliseconds, -1 for infinite
+-- @return          the event, or nil on timeout
+--
 function fwatcher.wait(timeout)
     return _instance:wait(timeout)
 end
diff --git a/xmake/core/base/hashset.lua b/xmake/core/base/hashset.lua
index 3342a0e60..c052d36ee 100644
--- a/xmake/core/base/hashset.lua
+++ b/xmake/core/base/hashset.lua
@@ -252,6 +252,10 @@ function hashset:clone()
 end
 
 -- construct from list of items
+--
+-- @param ...   the items to insert
+-- @return      the new hashset
+--
 function hashset.of(...)
     local result = hashset.new()
     local data = table.pack(...)
@@ -262,6 +266,10 @@ function hashset.of(...)
 end
 
 -- construct from an array
+--
+-- @param array the array of items to insert
+-- @return      the new hashset
+--
 function hashset.from(array)
     local result = hashset.new()
     for i = 1, #array do
@@ -270,7 +278,10 @@ function hashset.from(array)
     return result
 end
 
--- new hashset
+-- create a new empty hashset
+--
+-- @return      the new hashset
+--
 function hashset.new()
     return hashset {{}, 0}
 end
diff --git a/xmake/core/base/semver.lua b/xmake/core/base/semver.lua
index 5858ef7c2..7c2b6ea8d 100644
--- a/xmake/core/base/semver.lua
+++ b/xmake/core/base/semver.lua
@@ -191,7 +191,11 @@ function _instance.__concat(op1, op2)
     end
 end
 
--- new an instance
+-- create a new semver instance
+--
+-- @param version   the version string, e.g. "1.2.3", ">=1.0 <2.0"
+-- @return          the semver instance, or nil and error info
+--
 function semver.new(version)
 
     -- parse version first
@@ -207,6 +211,12 @@ function semver.new(version)
 end
 
 -- try to match valid version from string
+--
+-- @param str       the input string
+-- @param pos       the start position (optional, default is 1)
+-- @param pattern   the match patterns (optional)
+-- @return          the semver instance, or nil if not found
+--
 function semver.match(str, pos, pattern)
     local patterns = pattern or {"%d+[.]%d+[-+.%w]*", "%d+[.]%d+[.]%d+", "%d+[.]%d+"}
     for _, pattern in ipairs(table.wrap(patterns)) do
diff --git a/xmake/core/base/signal.lua b/xmake/core/base/signal.lua
index ee1094c52..a647204ef 100644
--- a/xmake/core/base/signal.lua
+++ b/xmake/core/base/signal.lua
@@ -28,16 +28,26 @@ local os = require("base/os")
 signal.SIGINT = 2
 
 -- register signal handler
+--
+-- @param signo     the signal number, e.g. signal.SIGINT
+-- @param handler   the handler function
+--
 function signal.register(signo, handler)
     os.signal(signo, handler)
 end
 
--- reset signal, SIGDFL
+-- reset signal to default handler (SIGDFL)
+--
+-- @param signo     the signal number
+--
 function signal.reset(signo)
     os.signal(signo, 1)
 end
 
--- ignore signal, SIGIGN
+-- ignore signal (SIGIGN)
+--
+-- @param signo     the signal number
+--
 function signal.ignore(signo)
     os.signal(signo, 2)
 end
diff --git a/xmake/core/base/table.lua b/xmake/core/base/table.lua
index 45cb4f23d..6be5893d6 100644
--- a/xmake/core/base/table.lua
+++ b/xmake/core/base/table.lua
@@ -89,7 +89,11 @@ if xmake._ARCH:startswith("arm") then
     end
 end
 
--- join all objects and tables
+-- join all objects and tables into a new table
+--
+-- @param ...   the tables or values to join
+-- @return      the new joined table
+--
 function table.join(...)
     local result = {}
     for _, t in ipairs({...}) do
@@ -105,7 +109,12 @@ function table.join(...)
     return result
 end
 
--- join all objects and tables to self
+-- join all objects and tables to self (in-place)
+--
+-- @param self  the destination table
+-- @param ...   the tables or values to append
+-- @return      the destination table
+--
 function table.join2(self, ...)
     for _, t in ipairs({...}) do
         if type(t) == "table" and not t.__wrap_locked__ then
@@ -189,6 +198,10 @@ function table.copy2(self, copied)
 end
 
 -- inherit interfaces and create a new instance
+--
+-- @param ...   the base classes to inherit from
+-- @return      the new instance with inherited interfaces
+--
 function table.inherit(...)
     local classes = {...}
     local instance = {}
@@ -240,6 +253,13 @@ function table.inherit2(self, ...)
 end
 
 -- slice table array
+--
+-- @param self  the source array
+-- @param first the start index (default: 1)
+-- @param last  the end index (default: #self)
+-- @param step  the step (default: 1)
+-- @return      the sliced array
+--
 function table.slice(self, first, last, step)
     local sliced = {}
     for i = first or 1, last or #self, step or 1 do
@@ -258,8 +278,12 @@ function table.is_dictionary(dict)
     return type(dict) == "table" and dict[1] == nil
 end
 
--- does contain the given values in table?
--- contains arg1 or arg2 ...
+-- does the table contain any of the given values?
+--
+-- @param t     the table
+-- @param ...   the values to check (returns true if any is found)
+-- @return      true if any value is found
+--
 function table.contains(t, arg1, arg2, ...)
     local found = false
     if arg2 == nil then -- only one value
@@ -325,7 +349,11 @@ function table.to_array(iterator, state, var)
     return result, count
 end
 
--- unwrap array if be only one value
+-- unwrap array, return the value directly if only one element
+--
+-- @param array the array table
+-- @return      the single value, or the original array if multiple elements
+--
 function table.unwrap(array)
     if type(array) == "table" and not array.__wrap_locked__ then
         if #array == 1 then
@@ -335,7 +363,11 @@ function table.unwrap(array)
     return array
 end
 
--- wrap value to array
+-- wrap value to array, ensure the result is always a table
+--
+-- @param value the value (nil returns {}, table returns as-is, other wraps in {})
+-- @return      the array table
+--
 function table.wrap(value)
     if nil == value then
         return {}
@@ -365,7 +397,12 @@ function table.wrap_unlock(value)
     return value
 end
 
--- remove repeat from the given array
+-- remove duplicate values from the given array
+--
+-- @param array     the array table
+-- @param barrier   keep order with barrier? (optional)
+-- @return          the deduplicated array
+--
 function table.unique(array, barrier)
     if table.is_array(array) then
         if table.getn(array) ~= 1 then
@@ -430,6 +467,10 @@ end
 table.unpack = table.unpack or unpack
 
 -- get keys of a table
+--
+-- @param tbl   the table
+-- @return      the keys array
+--
 function table.keys(tbl)
     local keyset = {}
     local n = 0
@@ -440,7 +481,12 @@ function table.keys(tbl)
     return keyset, n
 end
 
--- get order keys of a table
+-- get sorted keys of a table
+--
+-- @param tbl       the table
+-- @param callback  the sort comparator function (optional)
+-- @return          the sorted keys array
+--
 function table.orderkeys(tbl, callback)
     local callback = type(callback) == "function" and callback or nil
     local keys = table.keys(tbl)
@@ -475,6 +521,10 @@ function table.orderpairs(t, callback)
 end
 
 -- get values of a table
+--
+-- @param tbl   the table
+-- @return      the values array
+--
 function table.values(tbl)
     local valueset = {}
     local n = 0
@@ -514,6 +564,11 @@ function table.reverse(arr)
 end
 
 -- remove values if predicate is matched
+--
+-- @param tbl   the table
+-- @param pred  the predicate function, e.g. function(v, k) return v == "xxx" end
+-- @return      the modified table
+--
 function table.remove_if(tbl, pred)
     if table.is_array(tbl) then
         for i = #tbl, 1, -1 do
@@ -537,6 +592,11 @@ function table.empty(tbl)
 end
 
 -- return indices or keys for the given value
+--
+-- @param tbl   the table
+-- @param value the value to find
+-- @return      the index/key, or nil if not found
+--
 function table.find(tbl, value)
     local result
     if table.is_array(tbl) then
diff --git a/xmake/core/base/winos.lua b/xmake/core/base/winos.lua
index 9d786fdfc..d43f08262 100644
--- a/xmake/core/base/winos.lua
+++ b/xmake/core/base/winos.lua
@@ -33,6 +33,10 @@ winos._registry_keys   = winos._registry_keys or winos.registry_keys
 winos._registry_values = winos._registry_values or winos.registry_values
 winos._processes       = winos._processes or winos.processes
 
+-- get the ANSI code page
+--
+-- @return      the code page number
+--
 function winos.ansi_cp()
     if not winos._ANSI_CP then
          winos._ANSI_CP = winos._ansi_cp()
@@ -40,6 +44,10 @@ function winos.ansi_cp()
     return winos._ANSI_CP
 end
 
+-- get the OEM code page
+--
+-- @return      the code page number
+--
 function winos.oem_cp()
     if not winos._OEM_CP then
          winos._OEM_CP = winos._oem_cp()
@@ -114,7 +122,10 @@ function winos._version_le(self, version)
     end
 end
 
--- get system version
+-- get windows system version
+--
+-- @return      the version object, e.g. winos.version():major(), winos.version():eq("win10")
+--
 function winos.version()
     local winver = winos._VERSION
     if winver == nil then
@@ -156,6 +167,11 @@ function winos.version()
 end
 
 -- get command arguments on windows to solve 8192 character command line length limit
+--
+-- @param argv  the arguments list
+-- @param opt   the options, e.g. {program = "cl.exe", wrapflag = "@"}
+-- @return      the program, the new arguments list (may use @file)
+--
 function winos.cmdargv(argv, opt)
 
     -- too long arguments?