improve more modules commentscomments

22 files changed, 130 insertions, 1 deletions

diff --git a/xmake/modules/private/action/build/build_binary.lua b/xmake/modules/private/action/build/build_binary.lua
index 47884fd44..e53d6525a 100644
--- a/xmake/modules/private/action/build/build_binary.lua
+++ b/xmake/modules/private/action/build/build_binary.lua
@@ -22,6 +22,12 @@
 import("build_object")
 import("private.action.build.target", {alias = "target_buildutils"})
 
+-- build binary target
+--
+-- @param jobgraph  the job graph for dependency tracking
+-- @param target    the target instance
+-- @param opt       the options
+--
 function main(jobgraph, target, opt)
     opt = opt or {}
     local objects_group = target:fullname() .. "/objects"
diff --git a/xmake/modules/private/action/build/build_moduleonly.lua b/xmake/modules/private/action/build/build_moduleonly.lua
index e13693cab..bbaa8a079 100644
--- a/xmake/modules/private/action/build/build_moduleonly.lua
+++ b/xmake/modules/private/action/build/build_moduleonly.lua
@@ -21,6 +21,12 @@
 -- imports
 import("build_object")
 
+-- build module-only target
+--
+-- @param jobgraph  the job graph for dependency tracking
+-- @param target    the target instance
+-- @param opt       the options
+--
 function main(jobgraph, target, opt)
     build_object(jobgraph, target, opt)
 end
diff --git a/xmake/modules/private/action/build/build_object.lua b/xmake/modules/private/action/build/build_object.lua
index 1b5a26c72..2f48b730e 100644
--- a/xmake/modules/private/action/build/build_object.lua
+++ b/xmake/modules/private/action/build/build_object.lua
@@ -21,6 +21,12 @@
 -- imports
 import("private.action.build.target", {alias = "target_buildutils"})
 
+-- build object files target
+--
+-- @param jobgraph  the job graph for dependency tracking
+-- @param target    the target instance
+-- @param opt       the options
+--
 function main(jobgraph, target, opt)
     target_buildutils.add_filejobs(jobgraph, target, opt)
 end
diff --git a/xmake/modules/private/action/build/build_shared.lua b/xmake/modules/private/action/build/build_shared.lua
index 95aa3800c..11f2e2e17 100644
--- a/xmake/modules/private/action/build/build_shared.lua
+++ b/xmake/modules/private/action/build/build_shared.lua
@@ -21,6 +21,12 @@
 -- imports
 import("build_binary")
 
+-- build shared library target
+--
+-- @param jobgraph  the job graph for dependency tracking
+-- @param target    the target instance
+-- @param opt       the options
+--
 function main(jobgraph, target, opt)
     build_binary(jobgraph, target, opt)
 end
diff --git a/xmake/modules/private/action/build/build_static.lua b/xmake/modules/private/action/build/build_static.lua
index 028b83fbf..929640acb 100644
--- a/xmake/modules/private/action/build/build_static.lua
+++ b/xmake/modules/private/action/build/build_static.lua
@@ -21,6 +21,12 @@
 -- imports
 import("build_binary")
 
+-- build static library target
+--
+-- @param jobgraph  the job graph for dependency tracking
+-- @param target    the target instance
+-- @param opt       the options
+--
 function main(jobgraph, target, opt)
     build_binary(jobgraph, target, opt)
 end
diff --git a/xmake/modules/private/action/build/link_objects.lua b/xmake/modules/private/action/build/link_objects.lua
index 54d03da09..f2fede1ec 100644
--- a/xmake/modules/private/action/build/link_objects.lua
+++ b/xmake/modules/private/action/build/link_objects.lua
@@ -61,6 +61,12 @@ function _do_link_target(target, opt)
           values = depvalues, files = depfiles, dryrun = dryrun})
 end
 
+-- link object files to the target file
+--
+-- @param jobgraph  the job graph for dependency tracking
+-- @param target    the target instance
+-- @param opt       the options
+--
 function main(jobgraph, target, opt)
     opt = opt or {}
     local buildcmds = opt.buildcmds
diff --git a/xmake/modules/private/action/build/object.lua b/xmake/modules/private/action/build/object.lua
index 837c5fec4..7b9d4afee 100644
--- a/xmake/modules/private/action/build/object.lua
+++ b/xmake/modules/private/action/build/object.lua
@@ -171,6 +171,13 @@ function _add_jobgraph(target, jobgraph, sourcebatch, opt)
     end
 end
 
+-- build object files from source batch
+--
+-- @param target       the target instance
+-- @param jobgraph    the job graph for dependency tracking
+-- @param sourcebatch  the source batch {sourcefiles, sourcekind, ...}
+-- @param opt          the options, e.g. {progress = {}}
+--
 function main(target, jobgraph, sourcebatch, opt)
     opt = opt or {}
     if jobgraph.add_orders then
diff --git a/xmake/modules/private/action/build/prepare_files.lua b/xmake/modules/private/action/build/prepare_files.lua
index 0b37b5305..af7bf1a83 100644
--- a/xmake/modules/private/action/build/prepare_files.lua
+++ b/xmake/modules/private/action/build/prepare_files.lua
@@ -22,6 +22,12 @@
 import("core.base.option")
 import("private.action.build.target", {alias = "target_buildutils"})
 
+-- prepare source files for building
+--
+-- @param jobgraph  the job graph for dependency tracking
+-- @param target    the target instance
+-- @param opt       the options
+--
 function main(jobgraph, target, opt)
     target_buildutils.add_filejobs(jobgraph, target, opt)
 end
diff --git a/xmake/modules/private/action/require/impl/actions/check.lua b/xmake/modules/private/action/require/impl/actions/check.lua
index d6143fcfa..2bd840d75 100644
--- a/xmake/modules/private/action/require/impl/actions/check.lua
+++ b/xmake/modules/private/action/require/impl/actions/check.lua
@@ -22,7 +22,11 @@
 import("core.base.option")
 import("core.project.config")
 
--- check the given package
+-- check the package after installation
+--
+-- @param package  the package instance
+-- @param opt      the options
+--
 function main(package, opt)
     opt = opt or {}
 
diff --git a/xmake/modules/private/action/require/impl/actions/download.lua b/xmake/modules/private/action/require/impl/actions/download.lua
index 84c8d85be..5930b3cbb 100644
--- a/xmake/modules/private/action/require/impl/actions/download.lua
+++ b/xmake/modules/private/action/require/impl/actions/download.lua
@@ -323,6 +323,16 @@ function _urls(package)
 end
 
 -- download the given package
+-- download the package source
+--
+-- @param package  the package instance
+-- @param opt      the options
+--
+-- download the package source
+--
+-- @param package  the package instance
+-- @param opt      the options
+--
 function main(package, opt)
     opt = opt or {}
 
diff --git a/xmake/modules/private/action/require/impl/actions/download_resources.lua b/xmake/modules/private/action/require/impl/actions/download_resources.lua
index 30e7f9146..c185d25b0 100644
--- a/xmake/modules/private/action/require/impl/actions/download_resources.lua
+++ b/xmake/modules/private/action/require/impl/actions/download_resources.lua
@@ -164,6 +164,14 @@ function _download(package, resource_name, resource_url, resource_hash)
 end
 
 -- download all resources of the given package
+-- download the package resources
+--
+-- @param package  the package instance
+--
+-- download the package resources
+--
+-- @param package  the package instance
+--
 function main(package)
 
     -- we don't need to download it if we use the precompiled artifacts to install package
diff --git a/xmake/modules/private/action/require/impl/actions/install.lua b/xmake/modules/private/action/require/impl/actions/install.lua
index 94f8007b3..3789573b6 100644
--- a/xmake/modules/private/action/require/impl/actions/install.lua
+++ b/xmake/modules/private/action/require/impl/actions/install.lua
@@ -436,6 +436,10 @@ function _get_package_tipname(package)
     return package_tipname
 end
 
+-- install the package
+--
+-- @param package  the package instance
+--
 function main(package)
     local oldir = _enter_workdir(package)
 
diff --git a/xmake/modules/private/action/require/impl/actions/patch_sources.lua b/xmake/modules/private/action/require/impl/actions/patch_sources.lua
index 81f506420..6c18b69b1 100644
--- a/xmake/modules/private/action/require/impl/actions/patch_sources.lua
+++ b/xmake/modules/private/action/require/impl/actions/patch_sources.lua
@@ -143,6 +143,14 @@ function _patch(package, patchinfo)
 end
 
 -- patch the given package
+-- patch the package sources
+--
+-- @param package  the package instance
+--
+-- patch the package sources
+--
+-- @param package  the package instance
+--
 function main(package)
 
     -- we don't need to patch it if we use the precompiled artifacts to install package
diff --git a/xmake/modules/private/action/require/impl/actions/test.lua b/xmake/modules/private/action/require/impl/actions/test.lua
index f30d5febe..d07e5ece3 100644
--- a/xmake/modules/private/action/require/impl/actions/test.lua
+++ b/xmake/modules/private/action/require/impl/actions/test.lua
@@ -23,6 +23,14 @@ import("core.base.option")
 import("private.action.require.impl.utils.filter")
 
 -- test the given package
+-- test the installed package
+--
+-- @param package  the package instance
+--
+-- test the installed package
+--
+-- @param package  the package instance
+--
 function main(package)
 
     -- enter the test directory
diff --git a/xmake/modules/private/action/require/impl/download_packages.lua b/xmake/modules/private/action/require/impl/download_packages.lua
index b25038672..81bbdd074 100644
--- a/xmake/modules/private/action/require/impl/download_packages.lua
+++ b/xmake/modules/private/action/require/impl/download_packages.lua
@@ -232,6 +232,11 @@ function _download_packages(packages_download)
 end
 
 -- download packages
+-- download all required packages
+--
+-- @param requires  the requires table
+-- @param opt       the options
+--
 function main(requires, opt)
     opt = opt or {}
 
diff --git a/xmake/modules/private/action/require/impl/export_packages.lua b/xmake/modules/private/action/require/impl/export_packages.lua
index ee62efc4b..b4141a7e6 100644
--- a/xmake/modules/private/action/require/impl/export_packages.lua
+++ b/xmake/modules/private/action/require/impl/export_packages.lua
@@ -23,6 +23,11 @@ import("core.package.package", {alias = "core_package"})
 import("private.action.require.impl.package")
 
 -- export packages
+-- export required packages to a directory
+--
+-- @param requires  the requires table
+-- @param opt       the options
+--
 function main(requires, opt)
     opt = opt or {}
     local packages = {}
diff --git a/xmake/modules/private/action/require/impl/import_packages.lua b/xmake/modules/private/action/require/impl/import_packages.lua
index 1d11e1a06..134cf63bd 100644
--- a/xmake/modules/private/action/require/impl/import_packages.lua
+++ b/xmake/modules/private/action/require/impl/import_packages.lua
@@ -23,6 +23,11 @@ import("core.package.package", {alias = "core_package"})
 import("private.action.require.impl.package")
 
 -- import packages
+-- import packages from an exported directory
+--
+-- @param requires  the requires table
+-- @param opt       the options
+--
 function main(requires, opt)
     opt = opt or {}
     local packages = {}
diff --git a/xmake/modules/private/action/require/impl/install_packages.lua b/xmake/modules/private/action/require/impl/install_packages.lua
index 359f9ac47..bd7d59606 100644
--- a/xmake/modules/private/action/require/impl/install_packages.lua
+++ b/xmake/modules/private/action/require/impl/install_packages.lua
@@ -843,6 +843,11 @@ function _install_packages(requires, opt)
     return packages
 end
 
+-- install all required packages
+--
+-- @param requires  the requires table
+-- @param opt       the options
+--
 function main(requires, opt)
     -- we need to install toolchain packages first,
     -- because we will call compiler-specific api in package.on_load,
diff --git a/xmake/modules/private/action/require/impl/lock_packages.lua b/xmake/modules/private/action/require/impl/lock_packages.lua
index 61cc19a85..4609146b7 100644
--- a/xmake/modules/private/action/require/impl/lock_packages.lua
+++ b/xmake/modules/private/action/require/impl/lock_packages.lua
@@ -48,6 +48,10 @@ function _lock_package(instance)
 end
 
 -- lock all required packages
+-- lock package versions
+--
+-- @param packages  the packages table
+--
 function main(packages)
     if project.policy("package.requires_lock") then
         local plat = config.plat() or os.subhost()
diff --git a/xmake/modules/private/action/require/impl/register_packages.lua b/xmake/modules/private/action/require/impl/register_packages.lua
index e06f9d5cb..94d93b523 100644
--- a/xmake/modules/private/action/require/impl/register_packages.lua
+++ b/xmake/modules/private/action/require/impl/register_packages.lua
@@ -133,6 +133,10 @@ function _register_required_package(instance, required_package)
 end
 
 -- register all required root packages to local cache
+-- register all packages to targets
+--
+-- @param packages  the packages table
+--
 function main(packages)
 
     -- register to package cache for add_packages()
diff --git a/xmake/modules/private/action/require/impl/search_packages.lua b/xmake/modules/private/action/require/impl/search_packages.lua
index f8195afcb..38c4f05a1 100644
--- a/xmake/modules/private/action/require/impl/search_packages.lua
+++ b/xmake/modules/private/action/require/impl/search_packages.lua
@@ -40,6 +40,11 @@ function _search_packages(name, opt)
 end
 
 -- search packages
+-- search packages by names
+--
+-- @param names  the package names to search
+-- @param opt    the options
+--
 function main(names, opt)
     local results = {}
     for _, name in ipairs(names) do
diff --git a/xmake/modules/private/action/require/impl/uninstall_packages.lua b/xmake/modules/private/action/require/impl/uninstall_packages.lua
index a51c3b05f..685b5c973 100644
--- a/xmake/modules/private/action/require/impl/uninstall_packages.lua
+++ b/xmake/modules/private/action/require/impl/uninstall_packages.lua
@@ -23,6 +23,11 @@ import("core.cache.localcache")
 import("private.action.require.impl.package")
 
 -- uninstall packages
+-- uninstall required packages
+--
+-- @param requires  the requires table
+-- @param opt       the options
+--
 function main(requires, opt)
 
     -- init options