update more comments

4 files changed, 101 insertions, 15 deletions

diff --git a/xmake/core/base/filter.lua b/xmake/core/base/filter.lua
index dae397e4e..0312c4fa5 100644
--- a/xmake/core/base/filter.lua
+++ b/xmake/core/base/filter.lua
@@ -33,7 +33,10 @@ local scheduler = require("base/scheduler")
 local escape_table1 = {["$"] = "\001", ["("] = "\002", [")"] = "\003", ["%"] = "\004"}
 local escape_table2 = {["\001"] = "$", ["\002"] = "(", ["\003"] = ")", ["\004"] = "%"}
 
--- new filter instance
+-- create a new filter instance for variable substitution
+--
+-- @return      the filter instance
+--
 function filter.new()
 
     -- init an filter instance
@@ -51,7 +54,10 @@ end
 -- e.g.
 --
 -- print("$(shell echo hello xmake)")
--- add_ldflags("$(shell pkg-config --libs sqlite3)")
+-- execute shell command and return output for $(shell ...) substitution
+--
+-- @param cmd   the shell command
+-- @return      the command output string
 --
 function filter.shell(cmd)
 
@@ -77,12 +83,20 @@ function filter.shell(cmd)
     return outdata
 end
 
--- filter the environment variables
+-- get environment variable value for $(env ...) substitution
+--
+-- @param name  the environment variable name
+-- @return      the environment value
+--
 function filter.env(name)
     return os.getenv(name)
 end
 
--- filter the winreg path
+-- query windows registry value for $(reg ...) substitution
+--
+-- @param path  the registry path
+-- @return      the registry value
+--
 function filter.reg(path)
 
     -- must be windows
diff --git a/xmake/core/project/policy.lua b/xmake/core/project/policy.lua
index 0cf184d91..617a792d6 100644
--- a/xmake/core/project/policy.lua
+++ b/xmake/core/project/policy.lua
@@ -30,6 +30,9 @@ local utils   = require("base/utils")
 local string  = require("base/string")
 
 -- get all defined policies
+--
+-- @return      the policies table {name = {description, ...}, ...}
+--
 function policy.policies()
     local policies = policy._POLICIES
     if not policies then
@@ -212,6 +215,10 @@ function policy.policies()
 end
 
 -- set policy default value
+--
+-- @param name  the policy name, e.g. "build.ccache"
+-- @param value the default value
+--
 function policy.set_default(name, value)
     local defined_policy = policy.policies()[name]
     if defined_policy then
@@ -221,7 +228,12 @@ function policy.set_default(name, value)
     end
 end
 
--- check policy value
+-- check and validate policy value
+--
+-- @param name  the policy name
+-- @param value the value to check
+-- @return      the validated value
+--
 function policy.check(name, value)
     local defined_policy = policy.policies()[name]
     if defined_policy then
diff --git a/xmake/core/project/rule.lua b/xmake/core/project/rule.lua
index c11c6e246..790f715fa 100644
--- a/xmake/core/project/rule.lua
+++ b/xmake/core/project/rule.lua
@@ -84,24 +84,42 @@ function _instance:clone()
     return instance
 end
 
--- get the rule info
+-- get the rule info value
+--
+-- @param name  the info name
+-- @return      the info value
+--
 function _instance:get(name)
     return self._INFO:get(name)
 end
 
 -- set the value to the rule info
+--
+-- @param name  the info name
+-- @param ...   the values
+--
 function _instance:set(name, ...)
     self._INFO:apival_set(name, ...)
     self:_invalidate(name)
 end
 
 -- add the value to the rule info
+--
+-- @param name  the info name
+-- @param ...   the values to add
+--
 function _instance:add(name, ...)
     self._INFO:apival_add(name, ...)
     self:_invalidate(name)
 end
 
 -- get the extra configuration
+--
+-- @param name  the config name
+-- @param item  the config item
+-- @param key   the config key (optional)
+-- @return      the extra config value
+--
 function _instance:extraconf(name, item, key)
     return self._INFO:extraconf(name, item, key)
 end
@@ -112,6 +130,9 @@ function _instance:extraconf_set(name, item, key, value)
 end
 
 -- get the rule name
+--
+-- @return      the rule name string
+--
 function _instance:name()
     return self._NAME
 end
@@ -171,7 +192,12 @@ function _instance:orderdeps()
     return self._ORDERDEPS
 end
 
--- get xxx_script
+-- get the rule script function (on_build, on_install, etc.)
+--
+-- @param name     the script name, e.g. "build", "install", "clean"
+-- @param generic  use generic script if platform-specific not found?
+-- @return         the script function
+--
 function _instance:script(name, generic)
 
     -- get script
diff --git a/xmake/core/tool/builder.lua b/xmake/core/tool/builder.lua
index e6c649580..a91b24ede 100644
--- a/xmake/core/tool/builder.lua
+++ b/xmake/core/tool/builder.lua
@@ -753,47 +753,81 @@ function builder:_preprocess_flags(flags)
     return results
 end
 
--- get the target
+-- get the associated target
+--
+-- @return      the target instance
+--
 function builder:target()
     return self._TARGET
 end
 
--- get tool name
+-- get the tool name, e.g. "gcc", "clang", "cl"
+--
+-- @return      the tool name string
+--
 function builder:name()
     return self:_tool():name()
 end
 
--- get tool kind
+-- get the tool kind, e.g. "cc", "cxx", "ld", "ar"
+--
+-- @return      the tool kind string
+--
 function builder:kind()
     return self:_tool():kind()
 end
 
--- get tool program
+-- get the tool program path
+--
+-- @return      the program path string
+--
 function builder:program()
     return self:_tool():program()
 end
 
--- get toolchain of this tool
+-- get the toolchain of this tool
+--
+-- @return      the toolchain instance
+--
 function builder:toolchain()
     return self:_tool():toolchain()
 end
 
--- get the run environments
+-- get the run environments for this tool
+--
+-- @return      the environments table
+--
 function builder:runenvs()
     return self:_tool():runenvs()
 end
 
 -- get properties of the tool
+--
+-- @param name  the property name
+-- @return      the property value
+--
 function builder:get(name)
     return self:_tool():get(name)
 end
 
--- has flags?
+-- check if the tool supports the given flags
+--
+-- @param flags     the flags to check
+-- @param flagkind  the flag kind (optional)
+-- @param opt       the options (optional)
+-- @return          true if supported
+--
 function builder:has_flags(flags, flagkind, opt)
     return self:_tool():has_flags(flags, flagkind, opt)
 end
 
--- map flags from name and values, e.g. linkdirs, links, defines
+-- map abstract flags to tool-specific flags
+--
+-- @param name      the flag category, e.g. "links", "defines", "includedirs"
+-- @param values    the values to map
+-- @param opt       the options (optional)
+-- @return          the mapped flags array
+--
 function builder:map_flags(name, values, opt)
     local flags  = {}
     local mapper = self:_tool()["nf_" .. name]