add more comments

21 files changed, 151 insertions, 7 deletions

diff --git a/xmake/modules/detect/sdks/find_cross_toolchain.lua b/xmake/modules/detect/sdks/find_cross_toolchain.lua
index 9b7076201..e4acdfa3e 100644
--- a/xmake/modules/detect/sdks/find_cross_toolchain.lua
+++ b/xmake/modules/detect/sdks/find_cross_toolchain.lua
@@ -74,6 +74,12 @@ end
 --
 -- @endcode
 --
+-- find cross-compilation toolchain
+--
+-- @param sdkdir the SDK directory
+-- @param opt    the options, e.g. {bindir = "", cross = "arm-linux-gnueabihf-"}
+-- @return       the toolchain info table {sdkdir, bindir, cross, ...}
+--
 function main(sdkdir, opt)
 
     -- init arguments
diff --git a/xmake/modules/detect/sdks/find_cuda.lua b/xmake/modules/detect/sdks/find_cuda.lua
index 5a90cc581..0f5887313 100644
--- a/xmake/modules/detect/sdks/find_cuda.lua
+++ b/xmake/modules/detect/sdks/find_cuda.lua
@@ -158,6 +158,12 @@ end
 --
 -- @endcode
 --
+-- find CUDA SDK
+--
+-- @param sdkdir the CUDA SDK directory (optional)
+-- @param opt    the options, e.g. {verbose = true, force = false}
+-- @return       the SDK info table {sdkdir, bindir, libdirs, includedirs, ...}
+--
 function main(sdkdir, opt)
 
     -- init arguments
diff --git a/xmake/modules/detect/sdks/find_mingw.lua b/xmake/modules/detect/sdks/find_mingw.lua
index bdf97983f..69084f5e4 100644
--- a/xmake/modules/detect/sdks/find_mingw.lua
+++ b/xmake/modules/detect/sdks/find_mingw.lua
@@ -131,6 +131,12 @@ end
 --
 -- @endcode
 --
+-- find MinGW SDK
+--
+-- @param sdkdir the MinGW SDK directory (optional)
+-- @param opt    the options, e.g. {verbose = true, force = false}
+-- @return       the SDK info table {sdkdir, bindir, cross, ...}
+--
 function main(sdkdir, opt)
     opt = opt or {}
 
diff --git a/xmake/modules/detect/sdks/find_ndk.lua b/xmake/modules/detect/sdks/find_ndk.lua
index 628a76c41..ce7a4b712 100644
--- a/xmake/modules/detect/sdks/find_ndk.lua
+++ b/xmake/modules/detect/sdks/find_ndk.lua
@@ -275,6 +275,12 @@ end
 --
 -- @endcode
 --
+-- find Android NDK SDK
+--
+-- @param sdkdir the NDK SDK directory (optional)
+-- @param opt    the options, e.g. {verbose = true, force = false}
+-- @return       the SDK info table {sdkdir, bindir, cross, sdkver, ...}
+--
 function main(sdkdir, opt)
 
     -- init arguments
diff --git a/xmake/modules/detect/sdks/find_qt.lua b/xmake/modules/detect/sdks/find_qt.lua
index a7aa8e57c..c40491948 100644
--- a/xmake/modules/detect/sdks/find_qt.lua
+++ b/xmake/modules/detect/sdks/find_qt.lua
@@ -333,6 +333,12 @@ end
 --
 -- @endcode
 --
+-- find Qt SDK
+--
+-- @param sdkdir the Qt SDK directory (optional)
+-- @param opt    the options, e.g. {verbose = true, force = false}
+-- @return       the SDK info table {sdkdir, bindir, libdir, includedir, ...}
+--
 function main(sdkdir, opt)
 
     -- init arguments
diff --git a/xmake/modules/detect/sdks/find_vcpkgdir.lua b/xmake/modules/detect/sdks/find_vcpkgdir.lua
index 0b1103c8d..0b504b1c8 100644
--- a/xmake/modules/detect/sdks/find_vcpkgdir.lua
+++ b/xmake/modules/detect/sdks/find_vcpkgdir.lua
@@ -26,6 +26,10 @@ import("core.cache.detectcache")
 import("lib.detect.find_tool")
 
 -- find vcpkgdir
+-- find the vcpkg installation directory
+--
+-- @return      the vcpkg directory path, or nil
+--
 function main()
     local vcpkgdir = detectcache:get("detect.sdks.find_vcpkgdir")
     if vcpkgdir == nil then
diff --git a/xmake/modules/lib/detect/check_bigendian.lua b/xmake/modules/lib/detect/check_bigendian.lua
index 8de9b99ac..82948493f 100644
--- a/xmake/modules/lib/detect/check_bigendian.lua
+++ b/xmake/modules/lib/detect/check_bigendian.lua
@@ -61,6 +61,11 @@ end
 -- local is_bigendian = check_bigendian()
 -- @endcode
 --
+-- check if the target system is big-endian
+--
+-- @param opt   the options, e.g. {target = target}
+-- @return      true if big-endian
+--
 function main(opt)
     local snippets = check_bigendian_template
     local ok, is_bigendian = check_cxxsnippets(snippets, table.join(table.wrap(opt), {binary_match = _byteorder_binary_match}))
diff --git a/xmake/modules/lib/detect/check_csnippets.lua b/xmake/modules/lib/detect/check_csnippets.lua
index a44e2c4d5..ea46686a4 100644
--- a/xmake/modules/lib/detect/check_csnippets.lua
+++ b/xmake/modules/lib/detect/check_csnippets.lua
@@ -44,6 +44,12 @@ import("lib.detect.check_cxsnippets")
 -- local ok = check_csnippets({snippet_name = "void test(){}", "#define TEST 1"}, {types = "wchar_t", includes = "stdio.h"})
 -- @endcode
 --
+-- check C code snippets for compilation
+--
+-- @param snippets   the code snippets table
+-- @param opt        the options, e.g. {target = target, includes = {}, configs = {}}
+-- @return           true and output on success, or false
+--
 function main(snippets, opt)
     return check_cxsnippets(snippets, table.join(table.wrap(opt), {sourcekind = "cc"}))
 end
diff --git a/xmake/modules/lib/detect/check_cxsnippets.lua b/xmake/modules/lib/detect/check_cxsnippets.lua
index ad0310082..1e7dc604b 100644
--- a/xmake/modules/lib/detect/check_cxsnippets.lua
+++ b/xmake/modules/lib/detect/check_cxsnippets.lua
@@ -171,6 +171,12 @@ end
 --  }]], {tryrun = true})
 -- @endcode
 --
+-- check C/C++ code snippets for compilation
+--
+-- @param snippets   the code snippets table
+-- @param opt        the options, e.g. {target = target, sourcekind = "cc", includes = {}, configs = {}}
+-- @return           true and output on success, or false
+--
 function main(snippets, opt)
 
     -- init options
diff --git a/xmake/modules/lib/detect/check_cxxsnippets.lua b/xmake/modules/lib/detect/check_cxxsnippets.lua
index 785569181..c463b50ff 100644
--- a/xmake/modules/lib/detect/check_cxxsnippets.lua
+++ b/xmake/modules/lib/detect/check_cxxsnippets.lua
@@ -44,6 +44,12 @@ import("lib.detect.check_cxsnippets")
 -- local ok = check_cxxsnippets({snippet_name = "void test(){}", "#define TEST 1"}, {types = "wchar_t", includes = "stdio.h"})
 -- @endcode
 --
+-- check C++ code snippets for compilation
+--
+-- @param snippets   the code snippets table
+-- @param opt        the options, e.g. {target = target, includes = {}, configs = {}}
+-- @return           true and output on success, or false
+--
 function main(snippets, opt)
     return check_cxsnippets(snippets, table.join(table.wrap(opt), {sourcekind = "cxx"}))
 end
diff --git a/xmake/modules/lib/detect/check_sizeof.lua b/xmake/modules/lib/detect/check_sizeof.lua
index d6176b69a..ffd9dfcd9 100644
--- a/xmake/modules/lib/detect/check_sizeof.lua
+++ b/xmake/modules/lib/detect/check_sizeof.lua
@@ -63,6 +63,12 @@ end
 -- local size = check_sizeof("std::string", {includes = "string"})
 -- @endcode
 --
+-- check the size of a C/C++ type
+--
+-- @param typename   the type name, e.g. "int", "size_t"
+-- @param opt        the options, e.g. {includes = {"stddef.h"}, target = target}
+-- @return           the type size in bytes, or -1
+--
 function main(typename, opt)
     local snippets = check_sizeof_template:gsub('${TYPE}', typename)
     local ok, size = check_cxxsnippets(snippets, table.join(table.wrap(opt), {binary_match = _binary_match}))
diff --git a/xmake/modules/lib/detect/features.lua b/xmake/modules/lib/detect/features.lua
index 997acd2a1..4f0463181 100644
--- a/xmake/modules/lib/detect/features.lua
+++ b/xmake/modules/lib/detect/features.lua
@@ -35,6 +35,12 @@ import("core.base.scheduler")
 -- local features = features("clang", {flags = {"-g", "-O0"}, envs = {PATH = ""}})
 -- @endcode
 --
+-- get all supported features of the given tool
+--
+-- @param name  the tool name, e.g. "clang", "gcc"
+-- @param opt   the options, e.g. {program = "", flags = {}}
+-- @return      the features table, e.g. {cxx_constexpr = true}
+--
 function main(name, opt)
 
     -- init options
diff --git a/xmake/modules/lib/detect/find_package.lua b/xmake/modules/lib/detect/find_package.lua
index eedce1cec..3c53a3ca9 100644
--- a/xmake/modules/lib/detect/find_package.lua
+++ b/xmake/modules/lib/detect/find_package.lua
@@ -48,6 +48,12 @@ import("private.utils.package", {alias = "package_utils"})
 --
 -- @endcode
 --
+-- find package from system or package managers
+--
+-- @param name  the package name
+-- @param opt   the options, e.g. {require_version = ">=1.0", system = true, packagedirs = {}}
+-- @return      the package info table {links, linkdirs, includedirs, ...}, or nil
+--
 function main(name, opt)
 
     -- get the copied options
diff --git a/xmake/modules/net/fasturl.lua b/xmake/modules/net/fasturl.lua
index ff36805e1..90a9cd27c 100644
--- a/xmake/modules/net/fasturl.lua
+++ b/xmake/modules/net/fasturl.lua
@@ -29,6 +29,10 @@ function _parse_host(url)
     return host
 end
 
+-- add urls to the ping queue for later sorting
+--
+-- @param urls  the urls array to add
+--
 function add(urls)
     local pinginfo = _g._PINGINFO or {}
     _g._PINGHOSTS = _g._PINGHOSTS or {}
@@ -40,6 +44,11 @@ function add(urls)
     end
 end
 
+-- sort urls by network latency (fastest first)
+--
+-- @param urls  the urls array to sort
+-- @return      the sorted urls array
+--
 function sort(urls)
 
     -- ping hosts
diff --git a/xmake/modules/net/proxy.lua b/xmake/modules/net/proxy.lua
index 812fdc536..1ab9779e6 100644
--- a/xmake/modules/net/proxy.lua
+++ b/xmake/modules/net/proxy.lua
@@ -93,7 +93,11 @@ function _is_callable(func)
     end
 end
 
--- get proxy mirror url
+-- get proxy mirror url for the given url
+--
+-- @param url   the original url
+-- @return      the mirrored url
+--
 function mirror(url)
     local proxy_pac = _proxy_pac()
     if proxy_pac and proxy_pac.mirror then
@@ -142,8 +146,10 @@ function _global_proxy()
     return proxy
 end
 
--- get proxy configuration from the given url, [protocol://]host[:port]
+-- get proxy configuration for the given url
 --
+-- @param url   the target url
+-- @return      the proxy string, e.g. "socks5://127.0.0.1:1080", or nil
 -- @see https://github.com/xmake-io/xmake/issues/854
 --
 function config(url)
diff --git a/xmake/modules/private/utils/target.lua b/xmake/modules/private/utils/target.lua
index 56fb6faeb..217daad52 100644
--- a/xmake/modules/private/utils/target.lua
+++ b/xmake/modules/private/utils/target.lua
@@ -26,6 +26,12 @@ import("core.project.project")
 import("utils.binary.deplibs", {alias = "get_depend_libraries"})
 
 -- Is this target has these tools?
+-- check if the given tool is in the tools list
+--
+-- @param toolname   the tool name to check
+-- @param tools      the tools table
+-- @return           true if found
+--
 function has_tool(toolname, tools)
     if toolname then
         -- We need compatibility with gcc/g++, clang/clang++ for c++ compiler/linker
@@ -56,6 +62,13 @@ end
 -- only for clang: add_cxxflags("clang::-stdlib=libc++")
 -- only for clang and multiple flags: add_cxxflags("-stdlib=libc++", "-DFOO", {tools = "clang"})
 --
+-- check if a flag belongs to the given tool
+--
+-- @param flag        the flag string
+-- @param toolinst    the tool instance
+-- @param extraconf   the extra configuration
+-- @return            the flag if belongs, or nil
+--
 function flag_belong_to_tool(flag, toolinst, extraconf)
     local for_this_tool = true
     local flagconf = extraconf and extraconf[flag]
@@ -122,6 +135,10 @@ function translate_flags_in_tool(target, flagkind, flags)
 end
 
 -- get project targets
+-- get all enabled project targets
+--
+-- @return      the targets array
+--
 function get_project_targets()
     local selected_target = option.get("target")
     if selected_target then
@@ -169,6 +186,11 @@ function check_target_toolchains()
 end
 
 -- config target
+-- configure the given target (run on_config rules)
+--
+-- @param target    the target instance
+-- @param opt       the options (optional)
+--
 function config_target(target, opt)
     for _, rule in ipairs(table.wrap(target:orderules())) do
         local before_config = rule:script("config_before")
@@ -197,6 +219,10 @@ function config_target(target, opt)
 end
 
 -- config targets
+-- configure all project targets
+--
+-- @param opt   the options (optional)
+--
 function config_targets(opt)
     opt = opt or {}
     for _, target in ipairs(table.wrap(project.ordertargets())) do
diff --git a/xmake/modules/target/action/install/cmake_importfiles.lua b/xmake/modules/target/action/install/cmake_importfiles.lua
index c9c454554..4fc38a5aa 100644
--- a/xmake/modules/target/action/install/cmake_importfiles.lua
+++ b/xmake/modules/target/action/install/cmake_importfiles.lua
@@ -166,7 +166,11 @@ function _install_cmake_targetfile(target, installdir, filename, opt)
     end
 end
 
--- install .cmake import files
+-- install .cmake import files for the target
+--
+-- @param target    the target instance
+-- @param opt       the options, e.g. {installdir = "", libdir = ""}
+--
 function main(target, opt)
 
     -- check
diff --git a/xmake/modules/target/action/install/main.lua b/xmake/modules/target/action/install/main.lua
index 466ebe551..e86c63a75 100644
--- a/xmake/modules/target/action/install/main.lua
+++ b/xmake/modules/target/action/install/main.lua
@@ -214,6 +214,12 @@ function _install_moduleonly(target, opt)
     end
 end
 
+-- install the given target
+--
+-- @param target    the target instance
+-- @param opt       the options, e.g. {installdir = "", libdir = "", bindir = "", includedir = "",
+--                                     headers = true, binaries = true, libraries = true, packages = true}
+--
 function main(target, opt)
     opt = opt or {}
     if opt.headers == nil then
diff --git a/xmake/modules/target/action/install/pkgconfig_importfiles.lua b/xmake/modules/target/action/install/pkgconfig_importfiles.lua
index 9a9b8ee81..b0b91efa4 100644
--- a/xmake/modules/target/action/install/pkgconfig_importfiles.lua
+++ b/xmake/modules/target/action/install/pkgconfig_importfiles.lua
@@ -18,7 +18,11 @@
 -- @file        pkgconfig_importfiles.lua
 --
 
--- install pkgconfig/.pc import files
+-- install pkgconfig/.pc import files for the target
+--
+-- @param target    the target instance
+-- @param opt       the options, e.g. {installdir = "", libdir = "", includedir = ""}
+--
 function main(target, opt)
 
     -- check
diff --git a/xmake/modules/target/action/uninstall/main.lua b/xmake/modules/target/action/uninstall/main.lua
index a81aa63d8..bae3da830 100644
--- a/xmake/modules/target/action/uninstall/main.lua
+++ b/xmake/modules/target/action/uninstall/main.lua
@@ -154,6 +154,11 @@ function _uninstall_moduleonly(target, opt)
     _uninstall_headers(target, opt)
 end
 
+-- uninstall the given target
+--
+-- @param target    the target instance
+-- @param opt       the options, e.g. {installdir = "", libdir = "", bindir = "", includedir = ""}
+--
 function main(target, opt)
     opt = opt or {}
     local installdir = opt.installdir or target:installdir()
diff --git a/xmake/modules/utils/progress.lua b/xmake/modules/utils/progress.lua
index 8d7ab53f3..ac9c1e8f6 100644
--- a/xmake/modules/utils/progress.lua
+++ b/xmake/modules/utils/progress.lua
@@ -375,8 +375,11 @@ function _get_target_name_prefix(progress)
     end
 end
 
--- set the associated target name for the progress object (coroutine-local)
--- it's safe to call with non-table progress (e.g. number), it will be ignored
+-- set the associated target name for the progress display
+--
+-- @param progress  the progress object or number
+-- @param target    the target instance
+--
 function set_target(progress, target)
     if _is_show_target_enabled() and type(progress) == "table" and progress.set then
         progress:set("target_name", target:fullname())
@@ -510,7 +513,13 @@ function show_abort()
     end
 end
 
--- get the message text with progress
+-- get the formatted message text with progress (without printing)
+--
+-- @param progress  the progress value (0 ~ 100)
+-- @param format    the format string
+-- @param ...       the format arguments
+-- @return          the formatted text string
+--
 function text(progress, format, ...)
     local target_prefix = _get_target_name_prefix(progress)
     if target_prefix then