improve comments

4 files changed, 203 insertions, 13 deletions

diff --git a/xmake/core/base/hash.lua b/xmake/core/base/hash.lua
index d08a7d93b..4b37946e8 100644
--- a/xmake/core/base/hash.lua
+++ b/xmake/core/base/hash.lua
@@ -35,7 +35,11 @@ hash._rand32 = hash._rand32 or hash.rand32
 hash._rand64 = hash._rand64 or hash.rand64
 hash._rand128 = hash._rand128 or hash.rand128
 
--- generate md5 from the given file or data
+-- generate md5 hash from the given file or data
+--
+-- @param file_or_data  the file path, data string, or bytes object
+-- @return              the hash hex string, or nil and error info
+--
 function hash.md5(file_or_data)
     local hashstr, errors
     if bytes.instance_of(file_or_data) then
@@ -48,7 +52,11 @@ function hash.md5(file_or_data)
     return hashstr, errors
 end
 
--- generate sha1 from the given file or data
+-- generate sha1 hash from the given file or data
+--
+-- @param file_or_data  the file path, data string, or bytes object
+-- @return              the hash hex string, or nil and error info
+--
 function hash.sha1(file_or_data)
     local hashstr, errors
     if bytes.instance_of(file_or_data) then
@@ -61,7 +69,11 @@ function hash.sha1(file_or_data)
     return hashstr, errors
 end
 
--- generate sha256 from the given file or data
+-- generate sha256 hash from the given file or data
+--
+-- @param file_or_data  the file path, data string, or bytes object
+-- @return              the hash hex string, or nil and error info
+--
 function hash.sha256(file_or_data)
     local hashstr, errors
     if bytes.instance_of(file_or_data) then
@@ -75,11 +87,19 @@ function hash.sha256(file_or_data)
 end
 
 -- generate uuid, e.g "91E8ECF1-417F-4EDF-A574-E22D7D8D204A"
+--
+-- @param str   the seed string (optional, random if nil)
+-- @return      the uuid string
+--
 function hash.uuid(str)
     return hash.uuid4(str)
 end
 
 -- generate xxhash32 from the given file or data
+--
+-- @param file_or_data  the file path, data string, or bytes object
+-- @return              the hash hex string, or nil and error info
+--
 function hash.xxhash32(file_or_data)
     local hashstr, errors
     if bytes.instance_of(file_or_data) then
@@ -93,6 +113,10 @@ function hash.xxhash32(file_or_data)
 end
 
 -- generate xxhash64 from the given file or data
+--
+-- @param file_or_data  the file path, data string, or bytes object
+-- @return              the hash hex string, or nil and error info
+--
 function hash.xxhash64(file_or_data)
     local hashstr, errors
     if bytes.instance_of(file_or_data) then
@@ -106,6 +130,10 @@ function hash.xxhash64(file_or_data)
 end
 
 -- generate xxhash128 from the given file or data
+--
+-- @param file_or_data  the file path, data string, or bytes object
+-- @return              the hash hex string, or nil and error info
+--
 function hash.xxhash128(file_or_data)
     local hashstr, errors
     if bytes.instance_of(file_or_data) then
@@ -119,6 +147,10 @@ function hash.xxhash128(file_or_data)
 end
 
 -- generate hash32 from string, e.g. "91e8ecf1"
+--
+-- @param str   the input string
+-- @return      the 32-bit hash hex string
+--
 function hash.strhash32(str)
     if hash._rand32 then
         local data = libc.ptraddr(libc.dataptr(str))
@@ -131,6 +163,10 @@ function hash.strhash32(str)
 end
 
 -- generate hash64 from string, e.g. "91e8ecf191e8ecf1"
+--
+-- @param str   the input string
+-- @return      the 64-bit hash hex string
+--
 function hash.strhash64(str)
     local data = libc.ptraddr(libc.dataptr(str))
     local size = #str
@@ -138,14 +174,21 @@ function hash.strhash64(str)
 end
 
 -- generate hash128 from string, e.g. "91e8ecf1417f4edfa574e22d7d8d204a"
+--
+-- @param str   the input string
+-- @return      the 128-bit hash hex string
+--
 function hash.strhash128(str)
     local data = libc.ptraddr(libc.dataptr(str))
     local size = #str
     return hash._xxhash(128, data, size)
 end
 
--- generate random32 hash
--- @note it is easy to trigger hash conflicts
+-- generate random 32-bit hash
+--
+-- @return      the random hash hex string
+-- @note        it is easy to trigger hash conflicts
+--
 function hash.rand32()
     if hash._rand32 then
         return hash._rand32()
diff --git a/xmake/core/base/io.lua b/xmake/core/base/io.lua
index 3afd187d8..fd1350261 100644
--- a/xmake/core/base/io.lua
+++ b/xmake/core/base/io.lua
@@ -476,6 +476,11 @@ function _filelock:__gc()
 end
 
 -- read all lines from file
+--
+-- @param filepath  the file path
+-- @param opt       the options, e.g. {encoding = "utf8", continuation = "\\"}
+-- @return          the lines iterator
+--
 function io.lines(filepath, opt)
     opt = opt or {}
     if opt.close_on_finished == nil then
@@ -489,6 +494,11 @@ function io.lines(filepath, opt)
 end
 
 -- read all data from file
+--
+-- @param filepath  the file path
+-- @param opt       the options, e.g. {encoding = "utf8"}
+-- @return          the file content string
+--
 function io.readfile(filepath, opt)
     opt = opt or {}
     local file, errors = io.open(tostring(filepath), "r", opt)
@@ -525,6 +535,12 @@ function io.flush()
 end
 
 -- write data to file
+--
+-- @param filepath  the file path
+-- @param data      the data string
+-- @param opt       the options, e.g. {encoding = "utf8"}
+-- @return          true on success, or false and error info
+--
 function io.writefile(filepath, data, opt)
     opt = opt or {}
     local file, errors = io.open(tostring(filepath), "w", opt)
@@ -583,6 +599,10 @@ function io.open(filepath, mode, opt)
 end
 
 -- open a filelock
+--
+-- @param filepath  the lock file path
+-- @return          the filelock object
+--
 function io.openlock(filepath)
     filepath = tostring(filepath)
     local lock = io.filelock_open(filepath)
@@ -625,7 +645,13 @@ function io.convert(inputfile, outputfile, opt)
     return io.writefile(outputfile, content, {encoding = to})
 end
 
--- save object the the given filepath
+-- save object to the given filepath
+--
+-- @param filepath  the file path
+-- @param object    the object to serialize (table, string, number, boolean)
+-- @param opt       the options, e.g. {orderkeys = true}
+-- @return          true on success, or false and error info
+--
 function io.save(filepath, object, opt)
     opt = opt or {}
     assert(filepath and object)
@@ -659,6 +685,11 @@ function io.save(filepath, object, opt)
 end
 
 -- load object from the given file
+--
+-- @param filepath  the file path
+-- @param opt       the options, e.g. {encoding = "utf8"}
+-- @return          the deserialized object, or nil and error info
+--
 function io.load(filepath, opt)
     assert(filepath)
 
@@ -674,6 +705,13 @@ function io.load(filepath, opt)
 end
 
 -- gsub the given file and return replaced data
+--
+-- @param filepath  the file path
+-- @param pattern   the lua pattern string
+-- @param replace   the replacement string or function
+-- @param opt       the options, e.g. {encoding = "utf8"}
+-- @return          the replaced data string, the replacement count
+--
 function io.gsub(filepath, pattern, replace, opt)
 
     -- read all data from file
@@ -699,6 +737,13 @@ function io.gsub(filepath, pattern, replace, opt)
 end
 
 -- replace text of the given file and return new file data
+--
+-- @param filepath  the file path
+-- @param pattern   the plain text or lua pattern to search
+-- @param replace   the replacement string
+-- @param opt       the options, e.g. {plain = true, encoding = "utf8"}
+-- @return          the replaced data string, the replacement count
+--
 function io.replace(filepath, pattern, replace, opt)
     opt = opt or {}
     local data, errors = io.readfile(filepath, opt)
@@ -745,6 +790,12 @@ function io.insert(filepath, lineidx, text, opt)
 end
 
 -- cat the given file
+--
+-- @param filepath  the file path
+-- @param linecount the line count to read (optional, read all if nil)
+-- @param opt       the options, e.g. {encoding = "utf8"}
+-- @return          the file content string
+--
 function io.cat(filepath, linecount, opt)
     opt = opt or {}
     local file = io.open(filepath, "r", opt)
diff --git a/xmake/core/base/os.lua b/xmake/core/base/os.lua
index 142ddd338..9ba469505 100644
--- a/xmake/core/base/os.lua
+++ b/xmake/core/base/os.lua
@@ -577,6 +577,12 @@ function os.cp(srcpath, dstpath, opt)
 end
 
 -- move files or directories
+--
+-- @param srcpath   the source file/directory path, pattern is supported, e.g. "src/**.h"
+-- @param dstpath   the destination file/directory path
+-- @param opt       the options, e.g. {rootdir = "src"}
+-- @return          true on success, or false and error info
+--
 function os.mv(srcpath, dstpath, opt)
 
     -- check arguments
@@ -602,6 +608,11 @@ function os.mv(srcpath, dstpath, opt)
 end
 
 -- remove files or directories
+--
+-- @param filepath   the file/directory path, pattern is supported, e.g. "src/**.o"
+-- @param opt        the options, e.g. {emptydirs = true}
+-- @return           true on success, or false and error info
+--
 function os.rm(filepath, opt)
     opt = opt or {}
 
@@ -658,6 +669,10 @@ function os.ln(srcpath, dstpath, opt)
 end
 
 -- change to directory
+--
+-- @param dir       the directory path
+-- @return          the previous directory
+--
 function os.cd(dir)
     assert(dir)
 
@@ -711,6 +726,10 @@ function os.touch(filepath, opt)
 end
 
 -- create directories
+--
+-- @param dir       the directory path, will create parent directories automatically
+-- @return          true on success, or false and error info
+--
 function os.mkdir(dir)
 
     -- check arguments
@@ -732,6 +751,11 @@ function os.mkdir(dir)
 end
 
 -- remove directories
+--
+-- @param dir       the directory path
+-- @param opt       the options, e.g. {emptydirs = true}
+-- @return          true on success, or false and error info
+--
 function os.rmdir(dir, opt)
 
     -- check arguments
@@ -758,6 +782,9 @@ function os.rmdir(dir, opt)
 end
 
 -- get the current directory
+--
+-- @return          the current working directory
+--
 function os.curdir()
     local curdir = os._CURDIR
     if curdir == nil then
@@ -768,6 +795,10 @@ function os.curdir()
 end
 
 -- get the temporary directory
+--
+-- @param opt       the options, e.g. {ramdisk = false}
+-- @return          the temporary directory path
+--
 function os.tmpdir(opt)
 
     -- is in fakeroot? @note: uid always be 0 in root and fakeroot
@@ -866,6 +897,11 @@ function os.run(cmd)
 end
 
 -- run command with arguments list
+--
+-- @param program   the program path or name
+-- @param argv      the arguments list
+-- @param opt       the options, e.g. {envs = {}, curdir = "", detach = false}
+--
 function os.runv(program, argv, opt)
 
     -- init options
@@ -1101,6 +1137,12 @@ function os.iorun(cmd)
 end
 
 -- run command with arguments and return output and error data
+--
+-- @param program   the program path or name
+-- @param argv      the arguments list
+-- @param opt       the options, e.g. {envs = {}, curdir = "", stdin = ""}
+-- @return          the stdout data, the stderr data
+--
 function os.iorunv(program, argv, opt)
 
     -- make temporary output and error file
@@ -1264,6 +1306,10 @@ function os.is_subarch(...)
 end
 
 -- get the system null device
+--
+-- @param input     use as input device if true, otherwise as output device
+-- @return          the null device path, e.g. "/dev/null" or "nul"
+--
 function os.nuldev(input)
 
     if input then
diff --git a/xmake/core/base/path.lua b/xmake/core/base/path.lua
index 5af6daec9..0d2dadfba 100644
--- a/xmake/core/base/path.lua
+++ b/xmake/core/base/path.lua
@@ -165,8 +165,12 @@ function _instance:__todisplay()
     return "<path: " .. (self:empty() and "empty" or self:str()) .. ">"
 end
 
--- get unix-style path, it is usually used on windows
+-- get unix-style path (forward slashes), it is usually used on windows
+--
+-- @param p     the path
+-- @return      the unix-style path with forward slashes
 -- @see https://github.com/xmake-io/xmake/issues/4731
+--
 function path.unix(p)
     return (tostring(p):gsub(path.sep(), "/"))
 end
@@ -202,6 +206,11 @@ function path.normalize(p)
 end
 
 -- get the directory of the path
+--
+-- @param p     the path
+-- @param sep   the path separator (optional, auto-detect if nil)
+-- @return      the directory part, e.g. path.directory("/tmp/file.txt") => "/tmp"
+--
 function path.directory(p, sep)
     p = tostring(p)
     if path._directory then
@@ -225,6 +234,11 @@ function path.directory(p, sep)
 end
 
 -- get absolute path
+--
+-- @param p         the path
+-- @param rootdir   the root directory (optional, default is os.curdir())
+-- @return          the absolute path
+--
 function path.absolute(p, rootdir)
     if rootdir then
         rootdir = tostring(rootdir)
@@ -233,6 +247,11 @@ function path.absolute(p, rootdir)
 end
 
 -- get relative path
+--
+-- @param p         the path
+-- @param rootdir   the root directory (optional, default is os.curdir())
+-- @return          the relative path
+--
 function path.relative(p, rootdir)
     if rootdir then
         rootdir = tostring(rootdir)
@@ -241,6 +260,11 @@ function path.relative(p, rootdir)
 end
 
 -- get the filename of the path
+--
+-- @param p     the path
+-- @param sep   the path separator (optional)
+-- @return      the filename with extension, e.g. path.filename("/tmp/file.txt") => "file.txt"
+--
 function path.filename(p, sep)
     p = tostring(p)
     local i =  0
@@ -257,7 +281,11 @@ function path.filename(p, sep)
     end
 end
 
--- get the basename of the path
+-- get the basename of the path (filename without extension)
+--
+-- @param p     the path
+-- @return      the basename, e.g. path.basename("/tmp/file.txt") => "file"
+--
 function path.basename(p)
     p = tostring(p)
     local name = path.filename(p)
@@ -269,7 +297,13 @@ function path.basename(p)
     end
 end
 
--- get the file extension of the path: .xxx
+-- get the file extension of the path
+--
+-- @param p     the path
+-- @param level the extension level (optional, default is 1)
+-- @return      the extension, e.g. path.extension("file.txt") => ".txt"
+--              path.extension("file.tar.gz", 2) => ".tar.gz"
+--
 function path.extension(p, level)
     p = tostring(p)
     local i = p:lastof(".", true)
@@ -288,12 +322,21 @@ function path.extension(p, level)
 end
 
 -- join path
+--
+-- @param p     the first path component
+-- @param ...   the remaining path components
+-- @return      the joined path
+--
 function path.join(p, ...)
     p = tostring(p)
     return path.translate(p .. path.sep() .. table.concat({...}, path.sep()))
 end
 
 -- split path by the separator
+--
+-- @param p     the path
+-- @return      the path components table
+--
 function path.split(p)
     p = tostring(p)
     return p:split("[/\\]")
@@ -319,8 +362,11 @@ function path.envsep()
     return envsep
 end
 
--- split environment variable with `path.envsep()`,
--- also handles more speical cases such as posix flags and windows quoted paths
+-- split environment variable with `path.envsep()`
+--
+-- @param env_path  the environment variable value, e.g. "/usr/bin:/usr/local/bin"
+-- @return          the paths table
+--
 function path.splitenv(env_path)
     local result = {}
     if xmake._HOST == "windows" then
@@ -356,8 +402,12 @@ function path.splitenv(env_path)
     return result
 end
 
--- concat environment variable with `path.envsep()`,
--- also handles more speical cases such as posix flags and windows quoted paths
+-- concat environment variable with `path.envsep()`
+--
+-- @param paths     the paths table
+-- @param envsep    the separator (optional, default is path.envsep())
+-- @return          the joined environment variable string
+--
 function path.joinenv(paths, envsep)
     if not paths or #paths == 0 then
         return ""