update more comments

6 files changed, 101 insertions, 17 deletions

diff --git a/xmake/core/base/bloom_filter.lua b/xmake/core/base/bloom_filter.lua
index d7e6eb0e3..d82618be9 100644
--- a/xmake/core/base/bloom_filter.lua
+++ b/xmake/core/base/bloom_filter.lua
@@ -175,7 +175,14 @@ function _instance:__gc()
     end
 end
 
--- new a bloom filter, e.g. {probability = 0.001, hash_count = 3, item_maxn = 1000000}
+-- create a new bloom filter
+--
+-- @param opt   the options
+--              - probability:  false positive rate (default: 0.001), supports 0.1 ~ 0.000001
+--              - hash_count:   the hash function count (default: 3)
+--              - item_maxn:    the maximum item count (default: 1000000)
+-- @return      the bloom filter instance, or nil and error info
+--
 function bloom_filter.new(opt)
     opt = opt or {}
     local probability = opt.probability or 0.001
diff --git a/xmake/core/base/colors.lua b/xmake/core/base/colors.lua
index 48318413e..3d3d1d0bf 100644
--- a/xmake/core/base/colors.lua
+++ b/xmake/core/base/colors.lua
@@ -233,6 +233,10 @@ end
 -- "${hello xmake}"
 -- "${hello xmake $beer}"
 --
+-- @param str   the string with color/emoji markup
+-- @param opt   the options, e.g. {patch_reset = true, ignore = false}
+-- @return      the translated string with ANSI escape codes
+--
 function colors.translate(str, opt)
 
     -- check string
@@ -359,7 +363,11 @@ function colors.translate(str, opt)
     return str
 end
 
--- ignore all colors
+-- ignore all colors, strip color markup from string
+--
+-- @param str   the string with color markup
+-- @return      the plain string without colors
+--
 function colors.ignore(str)
     if str then
         -- strip "${red}" and "${theme color}"
diff --git a/xmake/core/base/cpu.lua b/xmake/core/base/cpu.lua
index 56d424f4a..d5ec3fffb 100644
--- a/xmake/core/base/cpu.lua
+++ b/xmake/core/base/cpu.lua
@@ -281,34 +281,53 @@ function cpu._statinfo(name)
     end
 end
 
--- get vendor id
+-- get cpu vendor id, e.g. "GenuineIntel", "AuthenticAMD"
+--
+-- @return      the vendor id string
+--
 function cpu.vendor()
     return cpu._info().vendor_id
 end
 
--- get cpu model
+-- get cpu model number
+--
+-- @return      the model number
+--
 function cpu.model()
     local cpu_model = cpu._info().cpu_model
     return cpu_model and tonumber(cpu_model)
 end
 
--- get cpu model name
+-- get cpu model name, e.g. "Intel(R) Core(TM) i7-10700K"
+--
+-- @return      the model name string
+--
 function cpu.model_name()
     return cpu._info().cpu_model_name
 end
 
--- get cpu family
+-- get cpu family number
+--
+-- @return      the family number
+--
 function cpu.family()
     local cpu_family = cpu._info().cpu_family
     return cpu_family and tonumber(cpu_family)
 end
 
--- get cpu features
+-- get cpu features string, e.g. "sse sse2 avx avx2"
+--
+-- @return      the features string (space separated)
+--
 function cpu.features()
     return cpu._info().cpu_features
 end
 
--- has the given feature?
+-- has the given cpu feature?
+--
+-- @param name  the feature name, e.g. "avx2", "sse4_2"
+-- @return      true if supported
+--
 function cpu.has_feature(name)
     local features = cpu._FEATURES
     if not features then
@@ -321,7 +340,10 @@ function cpu.has_feature(name)
     return features:has(name)
 end
 
--- get cpu micro architecture
+-- get cpu micro architecture, e.g. "skylake", "zen3"
+--
+-- @return      the micro architecture name, or nil if unknown
+--
 function cpu.march()
     local march = cpu._MARCH
     if march == nil then
@@ -336,17 +358,27 @@ function cpu.march()
     return march
 end
 
--- get cpu number
+-- get cpu core count
+--
+-- @return      the number of cpu cores
+--
 function cpu.number()
     return cpu._statinfo("ncpu")
 end
 
 -- get cpu usage rate
+--
+-- @return      the usage rate (0.0 ~ 1.0)
+--
 function cpu.usagerate()
     return cpu._statinfo("usagerate")
 end
 
--- get cpu info
+-- get all cpu info as a table
+--
+-- @param name  the specific info name (optional), e.g. "march", "ncpu"
+-- @return      the cpu info table or specific value
+--
 function cpu.info(name)
     local cpuinfo = {}
     cpuinfo.vendor     = cpu.vendor()
diff --git a/xmake/core/base/memory.lua b/xmake/core/base/memory.lua
index ff52658e5..5225a3c8a 100644
--- a/xmake/core/base/memory.lua
+++ b/xmake/core/base/memory.lua
@@ -25,6 +25,10 @@ local memory = memory or {}
 local os = require("base/os")
 
 -- get memory info
+--
+-- @param name  the specific info name (optional), e.g. "totalsize", "availsize", "usagerate"
+-- @return      the memory info table or specific value (sizes in bytes, usagerate in 0.0 ~ 1.0)
+--
 function memory.info(name)
     local meminfo = memory._MEMINFO
     local memtime = memory._MEMTIME
diff --git a/xmake/core/project/config.lua b/xmake/core/project/config.lua
index 93c1ff6af..451bfe8ae 100644
--- a/xmake/core/project/config.lua
+++ b/xmake/core/project/config.lua
@@ -69,7 +69,11 @@ function config._is_value(value, ...)
     return false
 end
 
--- get the current given configuration
+-- get the current given configuration value
+--
+-- @param name  the configuration name, e.g. "plat", "arch", "mode"
+-- @return      the configuration value
+--
 function config.get(name)
     local value = nil
     if config._CONFIGS then
@@ -105,17 +109,26 @@ function config.set(name, value, opt)
     end
 end
 
--- get the current platform
+-- get the current platform, e.g. "windows", "linux", "macosx"
+--
+-- @return      the platform name
+--
 function config.plat()
     return config.get("plat")
 end
 
--- get the current architecture
+-- get the current architecture, e.g. "x86_64", "arm64"
+--
+-- @return      the architecture name
+--
 function config.arch()
     return config.get("arch")
 end
 
--- get the current mode
+-- get the current build mode, e.g. "debug", "release"
+--
+-- @return      the mode name
+--
 function config.mode()
     return config.get("mode")
 end
@@ -189,6 +202,9 @@ function config.cachedir()
 end
 
 -- get the configure directory on the current host/arch platform
+--
+-- @return      the configuration cache directory, e.g. ".xmake/macosx/x86_64"
+--
 function config.directory()
     if config._DIRECTORY == nil then
         local rootdir = os.getenv("XMAKE_CONFIGDIR")
diff --git a/xmake/core/project/project.lua b/xmake/core/project/project.lua
index 7058b4190..f9e199a1b 100644
--- a/xmake/core/project/project.lua
+++ b/xmake/core/project/project.lua
@@ -818,6 +818,9 @@ function project.rcfiles()
 end
 
 -- get the project directory
+--
+-- @return      the project root directory path
+--
 function project.directory()
     return os.projectdir()
 end
@@ -862,6 +865,9 @@ function project.extraconf(name, item, key)
 end
 
 -- get the project name
+--
+-- @return      the project name string defined by set_project()
+--
 function project.name()
     local name = project.get("project")
     -- TODO multi project names? we only get the first name now.
@@ -987,7 +993,12 @@ function project.is_loaded()
     return project._memcache():get("targets_loaded")
 end
 
--- get the given target
+-- get the given target by name
+--
+-- @param name  the target name
+-- @param opt   the options (optional)
+-- @return      the target instance, or nil if not found
+--
 function project.target(name, opt)
     opt = opt or {}
     local targets = project.targets()
@@ -1009,7 +1020,10 @@ function project.target_add(t)
     end
 end
 
--- get targets
+-- get all targets
+--
+-- @return      the targets table {name = target_instance, ...}
+--
 function project.targets()
     local loading = false
     local targets = project._memcache():get("targets")
@@ -1079,6 +1093,9 @@ function project.required_package(name)
 end
 
 -- get required packages
+--
+-- @return      the required packages table {name = package_instance, ...}
+--
 function project.required_packages()
     local requires = project._memcache():get("requires")
     if not requires then